Popis saveznih država SAD-a ili kanadskih pokrajina s brojevima na zalihi

Ovim neobaveznim korakom za Sjedinjene Američke Države ili Kanadu suzite pretraživanje prema saveznoj državi ili pokrajini. Prihvaćaju se samo US i CA.

• Svaka stavka opisuje prefikse na zalihi za tu saveznu državu u trenutku zahtjeva.
• Slijedite next_function za prikaz popisa područja savezne države. Poveznica već uključuje filtar state, ali ne i pid.
• Pretraživanje područja uspoređuje podatke o saveznoj državi na malo drukčiji način. Ako poveznica savezne države next_function vrati No areas found, umjesto toga pozovite getareas bez navođenja savezne države.
• Provjerite status.code prije čitanja response. Nepodržana zemlja ili zemlja bez odgovarajuće zalihe vraća kod 404 bez odgovarajućeg HTTP statusa.
• Prazan popis s kodom 200 znači da zaliha postoji, ali ne sadrži podatke o saveznoj državi. Pozovite getareas bez navođenja savezne države.

Zahtjev

Obavezno: HTTP Basic autentifikacija ili Bearer token (pogledajte Autentifikacija i odgovori API-ja). Na neuspjelu autentifikaciju odgovara se s HTTP 401 prije izvršavanja pretraživanja.

GET s isocode u putanji. Ako se segment putanje izostavi, umjesto njega čita se polje isocode kodirano u formatu obrasca. Neobavezni parametar pid šalje se u nizu upita.

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

Odgovor

Standardna omotnica odgovora. U slučaju uspjeha status.code je 200, status.msg je prazan, a status.results je broj stavki. response je popis razvrstan prema polju name (bez razlikovanja velikih i malih slova), a zatim prema kodu u polju state. Polja: state (kod savezne države ili pokrajine preuzet iz podataka prefiksa o saveznoj državi, obično dva slova; neuobičajene vrijednosti prosljeđuju se neizmijenjene); name (naziv iz kataloga ili kod ako katalog za njega nema naziv); country_iso; available (ukupna zaliha svih prebrojenih prefiksa, uvijek veća od 0); prefix_count (broj prebrojenih prefiksa na zalihi); is_mobile (1 ako bilo koji prebrojeni prefiks podržava mobilnu telefoniju; uvijek 0 za US, osim ako su za vaš račun omogućeni mobilni brojevi SAD-a); sms_coverage (1 ako bilo koji prebrojeni prefiks ima SMS pokrivenost); returns_numbers (1 ako bilo koji prebrojeni prefiks ima oznaku za vraćanje brojeva ili za tu oznaku nema vrijednosti); next_function ('v3/getareas/{isocode}?state={state}'). Ako postoje prefiksi na zalihi, ali nijedan ne sadrži podatke o saveznoj državi, rezultat je status.code 200 s praznim popisom i status.results 0.

Ogledna struktura odgovora; ne predstavlja podatke računa u stvarnom vremenu ni trenutačnu ponudu.

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

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; pročitajte status.code.
• 404: msg 'getstates is only available for US and CA': bilo koji drugi kod zemlje. Ne postavlja se odgovarajući HTTP status.
• 404: msg 'No states found': nijedan prefiks na zalihi ne odgovara filtrima zemlje i izvora. Ne postavlja se odgovarajući HTTP status.
• 401: Autentifikacija nedostaje ili nije uspjela. Šalje se s HTTP statusom 401.

Dostupnost i popratni učinci

• Samo pretraživanje. Ništa ne rezervira, ne naručuje niti mijenja. available služi samo kao informacija i ne rezervira brojeve.