Seznam států USA nebo kanadských provincií s dostupnými čísly

Tento volitelný krok použijte pro Spojené státy nebo Kanadu k zúžení vyhledávání podle státu nebo provincie. Přijímány jsou pouze hodnoty US a CA.

• Každá položka popisuje prefixy s dostupnými čísly pro daný stát v okamžiku požadavku.
• Použijte odkaz next_function k vypsání oblastí daného státu. Již obsahuje filtr state, ale ne pid.
• Při vyhledávání oblastí se údaje o státu porovnávají mírně odlišně. Pokud odkaz daného státu next_function vrátí No areas found, zavolejte místo toho getareas bez zadání státu.
• Zkontrolujte status.code před čtením response. Pro nepodporovanou zemi nebo zemi bez odpovídajících dostupných čísel se vrací kód 404 bez odpovídajícího stavového kódu HTTP.
• Prázdný seznam s kódem 200 znamená, že dostupná čísla existují, ale neobsahují údaje o státu. Zavolejte getareas bez zadání státu.

Požadavek

Vyžadováno: ověřování HTTP Basic nebo token Bearer (viz Ověřování a odpovědi API). Při neúspěšném ověření se vrací HTTP 401 ještě před spuštěním vyhledávání.

GET s isocode v cestě. Pokud je tento segment cesty vynechán, načte se místo něj pole isocode kódované jako formulářová data. Volitelný parametr pid se odesílá v řetězci dotazu.

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

Odpověď

Standardní obálka odpovědi. Při úspěchu má status.code hodnotu 200, status.msg je prázdné a status.results udává počet položek. response je seznam seřazený podle name (bez rozlišení velkých a malých písmen) a následně podle kódu state. Pole: state (kód státu nebo provincie převzatý z údajů o státu u prefixů, obvykle tvořený dvěma písmeny; neobvyklé hodnoty se předávají beze změny); name (název z katalogu, nebo kód, pokud pro něj katalog nemá název); country_iso; available (celkový počet dostupných čísel ve všech započítávaných prefixech, vždy větší než 0); prefix_count (počet započítaných prefixů s dostupnými čísly); is_mobile (1, pokud některý započítaný prefix podporuje mobilní čísla; pro US vždy 0, pokud váš účet nemá povolena mobilní čísla USA); sms_coverage (1, pokud má některý započítaný prefix pokrytí SMS); returns_numbers (1, pokud má některý započítaný prefix nastaven příznak vracení čísel nebo u něj hodnota tohoto příznaku chybí); next_function ('v3/getareas/{isocode}?state={state}'). Pokud existují prefixy s dostupnými čísly, ale žádný neobsahuje údaje o státu, výsledkem je status.code s hodnotou 200, prázdný seznam a status.results s hodnotou 0.

Ukázková struktura odpovědi; nejde o živá data účtu ani o aktuální cenovou nabídku.

{
  "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"
    }
  ]
}

Chyby

• 500: msg 'ISO Code parameter is required': isocode chybí nebo je prázdné. Jde o opravitelnou chybu požadavku. Odpovídající stavový kód HTTP se nenastavuje; přečtěte status.code.
• 404: msg 'getstates is only available for US and CA': jakýkoli jiný kód země. Odpovídající stavový kód HTTP se nenastavuje.
• 404: msg 'No states found': filtrům země a zdroje neodpovídají žádné prefixy s dostupnými čísly. Odpovídající stavový kód HTTP se nenastavuje.
• 401: Ověření chybí nebo selhalo. Odesílá se se stavovým kódem HTTP 401.

Dostupnost a vedlejší účinky

• Pouze vyhledávání. Nic nerezervuje, neobjednává ani nemění. available má pouze informativní charakter a čísla nerezervuje.