Riigi katvuspiirkondade loend

Kui olete valinud riigi (ning USA või Kanada puhul soovi korral osariigi päringu getstates tulemustest), tehke päring getareas, et näha, millistes piirkondades numbreid pakutakse. Salvestage piirkonna uuid järgmise sammu jaoks.

Iga piirkonna puhul on järgmiseks sammuks üks kahest võimalusest:

• available > 0: next_function on v3/getprefixes/{uuid} ning ?state= lisatakse siis, kui filtreerisite osariigi järgi. Kasutage seda prefiksite sirvimiseks.
• available = 0: piirkonnal on prefiksid, kuid numbreid pole saadaval, ja next_function on v3/order/{uuid}. Selle sammu nõuded leiate tellimise dokumentatsioonist.

available on kogu piirkonna koguarv ka siis, kui filtreerite osariigi järgi. Osariigifilter aktsepteerib koodi või täisnime, kuid toimib ainult riikide US ja CA puhul. Kui osariigifilter tagastab No areas found, proovige uuesti ilma filtrita. Kontrollid tehakse järgmises järjekorras: puuduv riigikood, tundmatu riik, osariigifilter mõne muu riigi jaoks, vigane osariik, vastavate piirkondade puudumine. Iga selline juhtum tagastab koodi 500 või 404 väljal status.code, ilma vastava HTTP olekukoodita.

Päring

Nõutav: HTTP Basic autentimine või Bearer pääsutõend (vt „Autentimine ja API vastused“). Ebaõnnestunud autentimise korral vastatakse enne otsingu käivitamist HTTP olekukoodiga 401.

GET päring, mille URL-i tees on isocode ning päringustringis valikulised parameetrid state ja pid. Kui teesegment puudub, loetakse selle asemel vormingus application/x-www-form-urlencoded saadetud väli isocode.

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'

Vastus

Standardne vastuse ümbris. Õnnestumise korral on status.code väärtus 200, status.msg väärtus 'Results: N', status.results väärtus N ning response on piirkonna nime järgi sorditud loend. Väljad: uuid (piirkonna identifikaator, mille sisemist struktuuri ei tõlgendata ja mida kasutatakse järgmises sammus); country_uuid (32-märgiline riigi identifikaator, mille sisemist struktuuri ei tõlgendata ja mida hiljem ei vajata); name; area_type ja number_type (kataloogi kirjeldavad tunnused; kirjed ei pruugi tähistada kohalike numbrite tüüpe); country_iso; is_mobile (0 või 1, piirkonna mobiilitunnuste põhjal; riigi US puhul alati 0, välja arvatud juhul, kui teie kontol on lubatud riigi US mobiilinumbrid); available (saadaolevate numbrite koguarv piirkonna kõigi vastavate prefiksite lõikes, mitte ainult päringus määratud osariigis); sms_coverage (0 või 1); returns_numbers (0 või 1, piirkonna prefiksite suurim tunnuse väärtus); latitude ja longitude; state_iso; next_function. state_iso: osariigifiltri kasutamisel on see filtrile vastavaks tuvastatud kood. Riikide US ja CA puhul ilma filtrita on see osariik, mille nimi ühtib piirkonna nimega; vastasel juhul kasutatakse piirkonna salvestatud väärtust ning selle puudumisel piirkonna prefiksiandmetest tuletatud koodi. Teiste riikide puhul kasutatakse salvestatud väärtust, mis võib olla tühi. next_function väärtus on 'v3/getprefixes/{uuid}' (filtreerimise korral lisatakse '?state={code}'), kui available on suurem kui 0, vastasel juhul 'v3/order/{uuid}'. Piirkonnad, millel pole ühtegi vastavat prefiksit, jäetakse välja. Piirkonnad, millel on prefiksid, kuid pole saadaolevaid numbreid, tagastatakse välja available väärtusega 0.

Vastuse struktuuri näide; see ei ole konto tegelikud andmed ega kehtiv hinnapakkumine.

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

Vead

• 500: msg 'ISO Code parameter is required': isocode puudub või on tühi. See on parandatav päringuviga. Vastavat HTTP olekukoodi ei määrata.
• 404: msg 'Error: no such country': riigikood on tundmatu. Vastavat HTTP olekukoodi ei määrata.
• 404: msg 'State filter is only available for US and CA': mõne muu riigi jaoks saadeti parameetri state mittetühi väärtus. Vastavat HTTP olekukoodi ei määrata.
• 404: msg 'Invalid state': state ei ole selle riigi jaoks teadaolev kood ega nimi. Vastavat HTTP olekukoodi ei määrata.
• 404: msg 'No areas found': ükski piirkond ei vasta riigi-, allika- ja osariigifiltritele. Vastavat HTTP olekukoodi ei määrata.
• 401: autentimine puudub või ebaõnnestus. Saadetakse HTTP olekukoodiga 401.

Saadavus ja kõrvalmõjud

• Ainult andmete otsing kliendikontodele. See ei broneeri, telli ega muuda midagi.
• available on informatiivne ja võib enne järgmist sammu muutuda.