Listaa Yhdysvaltain osavaltiot tai Kanadan provinssit, joissa on numeroita varastossa

Tällä valinnaisella vaiheella voit rajata Yhdysvaltojen tai Kanadan haun osavaltioon tai provinssiin. Vain US ja CA hyväksytään.

• Jokainen tietue kuvaa kyseisen osavaltion prefiksejä, joilla on numeroita varastossa pyynnön tekohetkellä.
• Seuraa linkkiä next_function saadaksesi luettelon osavaltion alueista. Linkki sisältää jo state-suodattimen mutta ei parametria pid.
• Aluehaku vertaa osavaltiotietoja hieman eri tavalla. Jos osavaltion next_function palauttaa tuloksen No areas found, kutsu sen sijaan toimintoa getareas ilman osavaltiota.
• Tarkista kenttä status.code ennen kuin luet kentän response. Maa, jota ei tueta tai jonka varastossa ei ole hakuehtoja vastaavia numeroita, palauttaa koodin 404 ilman vastaavaa HTTP-tilakoodia.
• Tyhjä luettelo ja koodi 200 tarkoittavat, että numeroita on varastossa mutta osavaltiotiedot puuttuvat. Kutsu toimintoa getareas ilman osavaltiota.

Pyyntö

Pakollinen: HTTP Basic -todennus tai Bearer-tunniste (katso Todennus ja API-vastaukset). Jos todennus epäonnistuu, palautetaan HTTP 401 ennen haun suorittamista.

GET-pyyntö, jonka polussa on isocode. Jos polun osa jätetään pois, sen sijaan luetaan lomakekoodattu isocode-kenttä. Valinnainen pid lähetetään kyselymerkkijonossa.

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

Vastaus

Vakiomuotoinen vastausrakenne. Onnistuneessa pyynnössä status.code on 200, status.msg on tyhjä ja status.results on tietueiden määrä. response on luettelo, joka on lajiteltu ensin kentän name mukaan (kirjainkoosta riippumatta) ja sitten kentän state osavaltiokoodin mukaan. Kentät: state (prefiksien osavaltiotiedoista saatu osavaltion tai provinssin koodi, tavallisesti kaksi kirjainta; poikkeavat arvot välitetään muuttamattomina); name (luettelossa oleva nimi tai koodi, jos luettelossa ei ole sille nimeä); country_iso; available (varaston kokonaismäärä laskettujen prefiksien osalta, aina suurempi kuin 0); prefix_count (laskettujen prefiksien määrä, joilla on numeroita varastossa); is_mobile (1, jos jokin laskettu prefiksi tukee matkapuhelinnumeroita; aina 0 maakoodilla US, ellei tilillesi ole otettu käyttöön Yhdysvaltain matkapuhelinnumeroita); sms_coverage (1, jos jollakin lasketulla prefiksillä on SMS-kattavuus); returns_numbers (1, jos jollakin lasketulla prefiksillä on numeroiden palauttamisen ilmaisin tai jos sen arvo puuttuu); next_function ('v3/getareas/{isocode}?state={state}'). Jos on prefiksejä, joilla on numeroita varastossa, mutta yhdelläkään niistä ei ole osavaltiotietoja, tuloksena on status.code 200, tyhjä luettelo ja status.results 0.

Havainnollistava esimerkki vastauksen rakenteesta; ei reaaliaikaisia tilitietoja eikä voimassa olevaa tarjousta.

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

Virheet

• 500: msg 'ISO Code parameter is required': isocode puuttuu tai on tyhjä. Tämä on korjattavissa oleva pyyntövirhe. Vastaavaa HTTP-tilakoodia ei aseteta; lue kenttä status.code.
• 404: msg 'getstates is only available for US and CA': mikä tahansa muu maakoodi. Vastaavaa HTTP-tilakoodia ei aseteta.
• 404: msg 'No states found': mikään prefiksi, jolla on numeroita varastossa, ei vastaa maa- ja lähdesuodattimia. Vastaavaa HTTP-tilakoodia ei aseteta.
• 401: Todennus puuttuu tai epäonnistui. Lähetetään HTTP-tilakoodilla 401.

Saatavuus ja sivuvaikutukset

• Pelkkä haku. Se ei varaa, tilaa eikä muuta mitään. available on vain tiedoksi eikä varaa numeroita.