Seznam oblastí pokrytí pro danou zemi

Po výběru země (a v případě USA nebo Kanady případně také státu či provincie z getstates) zavolejte getareas a zjistěte, ve kterých oblastech jsou čísla nabízena. Uložte si identifikátor oblasti uuid pro další krok.

Pro každou oblast následuje jeden ze dvou kroků:

• available > 0: next_function má hodnotu v3/getprefixes/{uuid}, s řetězcem ?state= připojeným při použití filtru podle státu či provincie. Tento odkaz použijte k procházení předvoleb.
• available = 0: oblast má předvolby, ale žádná dostupná čísla, a next_function má hodnotu v3/order/{uuid}. Požadavky pro tento krok najdete v dokumentaci k objednávání.

available je celkový počet za celou oblast, i když filtrujete podle státu či provincie. Tento filtr přijímá kód nebo úplný název, ale funguje pouze pro US a CA. Pokud při použití filtru obdržíte No areas found, zkuste požadavek zopakovat bez filtru. Kontroly probíhají v tomto pořadí: chybějící kód země, neznámá země, filtr podle státu či provincie pro jinou zemi, neplatný stát či provincie, žádné odpovídající oblasti. Každý z těchto případů vrací kód 500 nebo 404 v status.code, bez odpovídajícího stavového kódu HTTP.

Požadavek

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

GET s parametrem isocode v cestě a volitelnými parametry state a pid v řetězci dotazu. Pokud je tento segment cesty vynechán, načte se místo něj pole isocode z dat kódovaných jako formulář.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Odpověď

Standardní obálka odpovědi. Při úspěchu má status.code hodnotu 200, status.msg hodnotu 'Results: N', status.results hodnotu N a response je seznam seřazený podle názvu oblasti. Pole: uuid (neprůhledný identifikátor oblasti používaný v dalším kroku); country_uuid (neprůhledný identifikátor země o délce 32 znaků, který později není potřeba); name; area_type a number_type (katalogové popisy; položky nemusí být typy místních čísel); country_iso; is_mobile (0 nebo 1, podle příznaků mobilních čísel dané oblasti; pro US vždy 0, pokud váš účet nemá povolena mobilní čísla pro US); available (celková zásoba čísel ve všech odpovídajících předvolbách oblasti, bez omezení na požadovaný stát či provincii); sms_coverage (0 nebo 1); returns_numbers (0 nebo 1, nejvyšší hodnota příznaku mezi předvolbami oblasti); latitude a longitude; state_iso; next_function. state_iso: při použití filtru podle státu či provincie jde o kód určený na základě filtru. Pro US a CA bez filtru jde o stát či provincii, jehož název se shoduje s názvem oblasti; jinak se použije uložená hodnota oblasti, a pokud ani ta není k dispozici, kód odvozený z údajů o předvolbách oblasti. U ostatních zemí jde o uloženou hodnotu, která může být prázdná. next_function má hodnotu 'v3/getprefixes/{uuid}' (s připojeným '?state={code}' při použití filtru), pokud je available větší než 0, jinak 'v3/order/{uuid}'. Oblasti bez jediné odpovídající předvolby se vynechávají. Oblasti s předvolbami, ale bez dostupných čísel se vracejí s hodnotou available 0.

Ukázka struktury odpovědi; nejde o aktuální údaje účtu ani o aktuální cenovou nabídku.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

Chyby

• 500: msg 'ISO Code parameter is required': parametr isocode chybí nebo je prázdný. Jde o chybu požadavku, kterou lze opravit. Odpovídající stavový kód HTTP se nenastavuje.
• 404: msg 'Error: no such country': kód země není znám. Odpovídající stavový kód HTTP se nenastavuje.
• 404: msg 'State filter is only available for US and CA': pro jinou zemi byla odeslána neprázdná hodnota parametru state. Odpovídající stavový kód HTTP se nenastavuje.
• 404: msg 'Invalid state': hodnota parametru state není ani známým kódem, ani známým názvem státu či provincie pro danou zemi. Odpovídající stavový kód HTTP se nenastavuje.
• 404: msg 'No areas found': žádná oblast neodpovídá filtrům země, zdroje a státu či provincie. 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í pro zákaznické účty. Nic nerezervuje, neobjednává ani nemění.
• available je informativní údaj a před dalším krokem se může změnit.