Popis područja pokrivenosti za državu

Nakon što odaberete državu (a za SAD ili Kanadu po želji i saveznu državu ili pokrajinu iz rezultata poziva getstates), pozovite getareas da biste vidjeli za koja se područja nude brojevi. Za područje sačuvajte uuid za sljedeći korak.

Svako područje vodi na jedan od dvaju sljedećih koraka:

• available > 0: next_function ima vrijednost v3/getprefixes/{uuid}, s dodatkom ?state= pri filtriranju prema saveznoj državi ili pokrajini. Upotrijebite tu putanju za pregled prefiksa.
• available = 0: područje ima prefikse, ali nema raspoloživih brojeva, a next_function ima vrijednost v3/order/{uuid}. U dokumentaciji za naručivanje pogledajte što je potrebno za taj korak.

available predstavlja ukupan broj za cijelo područje, čak i kada filtrirate prema saveznoj državi ili pokrajini. Taj filtar prihvaća oznaku ili puni naziv, ali radi samo za US i CA. Ako filtriranje prema saveznoj državi ili pokrajini vrati No areas found, pokušajte ponovno bez tog filtra. Provjere se provode ovim redoslijedom: nedostaje oznaka države, nepoznata država, filtar savezne države ili pokrajine za drugu državu, nevaljana savezna država ili pokrajina, nema odgovarajućih područja. U svakom od tih slučajeva vraća se kôd 500 ili 404 u polju status.code, bez odgovarajućeg HTTP statusa.

Zahtjev

Obavezno: HTTP autentifikacija Basic ili token Bearer (pogledajte Autentifikacija i odgovori API-ja). Ako autentifikacija ne uspije, vraća se HTTP 401 prije nego što se pretraživanje izvrši.

GET s parametrom isocode u putanji i neobaveznim parametrima state i pid u nizu upita. Ako se segment putanje izostavi, umjesto njega čita se polje isocode kodirano kao podatak obrasca.

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'

Odgovor

Standardna ovojnica odgovora. U slučaju uspjeha status.code ima vrijednost 200, status.msg ima vrijednost 'Results: N', status.results ima vrijednost N, a response je popis poredan po nazivu područja. Polja: uuid (neprozirni identifikator područja koji se upotrebljava u sljedećem koraku); country_uuid (neprozirni identifikator države od 32 znaka, koji poslije nije potreban); name; area_type i number_type (kataloški opisi; stavke ne predstavljaju nužno lokalne vrste brojeva); country_iso; is_mobile (0 ili 1, prema oznakama mobilnih brojeva za područje; uvijek 0 za US, osim ako je vašem računu omogućen pristup mobilnim brojevima za US); available (ukupna količina raspoloživih brojeva u svim odgovarajućim prefiksima područja, bez ograničenja na traženu saveznu državu ili pokrajinu); sms_coverage (0 ili 1); returns_numbers (0 ili 1, najviša vrijednost oznake među prefiksima područja); latitude i longitude; state_iso; next_function. state_iso: kada je primijenjen filtar savezne države ili pokrajine, to je oznaka utvrđena na temelju filtra. Za US i CA bez filtra to je oznaka savezne države ili pokrajine čiji je naziv jednak nazivu područja; u suprotnom se upotrebljava pohranjena vrijednost područja, a ako ni nje nema, oznaka izvedena iz podataka o prefiksima područja. Za ostale države to je pohranjena vrijednost, koja može biti prazna. next_function ima vrijednost 'v3/getprefixes/{uuid}' (uz dodatak '?state={code}' kada je primijenjen filtar) kada je available veći od 0, a u suprotnom 'v3/order/{uuid}'. Područja koja nemaju nijedan odgovarajući prefiks izostavljaju se. Područja koja imaju prefikse, ali nemaju raspoloživih brojeva, vraćaju se s vrijednošću polja available 0.

Primjer strukture odgovora; ne predstavlja stvarne podatke računa ni aktualnu cjenovnu ponudu.

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

Pogreške

• 500: msg 'ISO Code parameter is required': isocode nedostaje ili je prazan. To je pogreška u zahtjevu koja se može ispraviti. Ne postavlja se odgovarajući HTTP status.
• 404: msg 'Error: no such country': oznaka države nije poznata. Ne postavlja se odgovarajući HTTP status.
• 404: msg 'State filter is only available for US and CA': za drugu državu poslana je neprazna vrijednost parametra state. Ne postavlja se odgovarajući HTTP status.
• 404: msg 'Invalid state': state nije ni poznata oznaka ni poznat naziv savezne države ili pokrajine za tu državu. Ne postavlja se odgovarajući HTTP status.
• 404: msg 'No areas found': nijedno područje ne odgovara filtrima države, izvora te savezne države ili pokrajine. Ne postavlja se odgovarajući HTTP status.
• 401: Autentifikacija nedostaje ili nije uspjela. Šalje se uz HTTP status 401.

Raspoloživost i popratni učinci

• Samo pretraživanje, dostupno korisničkim računima. Ništa se ne rezervira, ne naručuje niti mijenja.
• available služi kao informacija i može se promijeniti prije sljedećeg koraka.