Készleten lévő telefonszámokkal rendelkező amerikai államok vagy kanadai tartományok listázása

Ezzel a nem kötelező lépéssel az Egyesült Államokban vagy Kanadában államra vagy tartományra szűkítheti a keresést. Csak a US és a CA országkód fogadható el.

• Minden bejegyzés az adott államban a kérés időpontjában készleten lévő előhívókat írja le.
• Kövesse a next_function hivatkozást az állam területeinek listázásához. Ez már tartalmazza a state szűrőt, de nem tartalmazza a következőt: pid.
• A területlekérdezés kissé eltérően egyezteti az államra vonatkozó adatokat. Ha egy állam next_function hivatkozása a következő eredményt adja: No areas found, akkor inkább a getareas függvényt hívja meg állam megadása nélkül.
• Ellenőrizze a status.code értékét, mielőtt kiolvassa a következőt: response. Nem támogatott ország vagy megfelelő készlettel nem rendelkező ország esetén a visszaadott kód 404, ennek megfelelő HTTP-állapot nélkül.
• Ha a lista üres, és a kód 200, az azt jelenti, hogy van készlet, de nem tartozik hozzá államra vonatkozó adat. Hívja meg a getareas függvényt állam megadása nélkül.

Kérés

Kötelező: HTTP Basic hitelesítés vagy Bearer token (lásd: Hitelesítés és API-válaszok). Sikertelen hitelesítés esetén a rendszer HTTP 401 választ ad még a lekérdezés végrehajtása előtt.

GET kérés, az útvonalban megadott isocode értékkel. Ha az útvonalszegmens hiányzik, a rendszer helyette egy űrlapkódolt isocode mezőt olvas be. A nem kötelező pid paramétert a lekérdezési karakterláncban kell elküldeni.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getstates/US'

Válasz

Szabványos válaszburkolat. Siker esetén a status.code értéke 200, a status.msg üres, a status.results pedig a bejegyzések száma. A response lista először a name szerint rendezett, a kis- és nagybetűk megkülönböztetése nélkül, majd a state kód szerint. Mezők: state (az előhívók államadataiból származó állam- vagy tartománykód, általában két betű; a szokatlan értékeket a rendszer változtatás nélkül továbbítja); name (a katalógusban szereplő név, vagy a kód, ha a katalógusban nem tartozik hozzá név); country_iso; available (a számításba vett előhívók teljes készlete, mindig nagyobb, mint 0); prefix_count (a számításba vett, készleten lévő előhívók száma); is_mobile (1, ha bármely számításba vett előhívó támogatja a mobilhasználatot; a US esetében mindig 0, kivéve, ha a fiókjában engedélyezve vannak az amerikai mobilszámok); sms_coverage (1, ha bármely számításba vett előhívó rendelkezik SMS-lefedettséggel); returns_numbers (1, ha bármely számításba vett előhívónál be van állítva a számok visszaadását jelző jelző, vagy nincs megadva annak értéke); next_function ('v3/getareas/{isocode}?state={state}'). Ha vannak készleten lévő előhívók, de egyikhez sem tartozik államra vonatkozó adat, a status.code értéke 200, a lista üres, a status.results értéke pedig 0.

Szemléltető válaszstruktúra; nem élő fiókadat és nem aktuális árajánlat.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 2
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

Hibák

• 500: msg 'ISO Code parameter is required': az isocode hiányzik vagy üres. Ez javítható kérési hiba. A rendszer nem állít be ennek megfelelő HTTP-állapotot; olvassa ki a status.code értékét.
• 404: msg 'getstates is only available for US and CA': bármely más országkód esetén. A rendszer nem állít be ennek megfelelő HTTP-állapotot.
• 404: msg 'No states found': egyetlen készleten lévő előhívó sem felel meg az ország- és forrásszűrőknek. A rendszer nem állít be ennek megfelelő HTTP-állapotot.
• 401: Hiányzó vagy sikertelen hitelesítés. HTTP 401 állapottal érkezik.

Elérhetőség és mellékhatások

• Kizárólag lekérdezés. Semmit sem foglal le, rendel meg vagy módosít. Az available csak tájékoztató jellegű, és nem foglal le telefonszámokat.