Pateikti šalies aprėpties sričių sąrašą

Pasirinkę šalį (o JAV arba Kanados atveju, jei norite, ir valstiją iš getstates), iškvieskite getareas, kad pamatytumėte, kur siūlomi numeriai. Kitam veiksmui išsaugokite srities uuid.

Kiekvienai sričiai galimas vienas iš dviejų tolesnių veiksmų:

• available > 0: next_function reikšmė yra v3/getprefixes/{uuid}, prie kurio pridedama ?state=, jei filtravote pagal valstiją. Naudokite jį prefiksams peržiūrėti.
• available = 0: sritis turi prefiksų, tačiau neturi turimų numerių, o next_function reikšmė yra v3/order/{uuid}. Šio veiksmo reikalavimus rasite užsakymo dokumentacijoje.

available yra bendras visos srities turimų numerių skaičius, net jei filtruojate pagal valstiją. Valstijos filtras priima kodą arba visą pavadinimą, tačiau veikia tik su US ir CA. Jei naudojant valstijos filtrą grąžinama No areas found, bandykite dar kartą be šio filtro. Patikros atliekamos tokia tvarka: trūkstamas šalies kodas, nežinoma šalis, valstijos filtras kitai šaliai, netinkama valstija, nėra atitinkančių sričių. Kiekvienu iš šių atvejų grąžinamas kodas 500 arba 404 lauke status.code, nenustatant atitinkamo HTTP būsenos kodo.

Užklausa

Būtinas HTTP Basic autentifikavimas arba Bearer prieigos raktas (žr. „Autentifikavimas ir API atsakymai“). Jei autentifikavimas nepavyksta, prieš atliekant paiešką grąžinamas HTTP 401 atsakymas.

GET užklausa su isocode kelyje ir neprivalomais state bei pid parametrais užklausos eilutėje. Jei kelio segmentas praleistas, vietoj jo nuskaitomas formos koduote užkoduotas isocode laukas.

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'

Atsakymas

Standartinė atsakymo struktūra. Sėkmės atveju status.code yra 200, status.msg yra 'Results: N', status.results yra N, o response yra pagal srities pavadinimą surikiuotas sąrašas. Laukai: uuid (neinterpretuojamas srities identifikatorius, naudojamas kitame veiksme); country_uuid (neinterpretuojamas 32 simbolių šalies identifikatorius, vėliau nereikalingas); name; area_type ir number_type (katalogo aprašai; įrašai nebūtinai nurodo vietinių numerių tipus); country_iso; is_mobile (0 arba 1, pagal srities mobiliojo ryšio požymius; US atveju visada 0, nebent jūsų paskyrai įjungta galimybė naudoti US mobiliojo ryšio numerius); available (bendras turimų numerių skaičius visuose atitinkančiuose srities prefiksuose, neapsiribojant užklausoje nurodyta valstija); sms_coverage (0 arba 1); returns_numbers (0 arba 1, didžiausia požymio reikšmė tarp srities prefiksų); latitude ir longitude; state_iso; next_function. state_iso: naudojant valstijos filtrą, tai pagal filtrą nustatytas kodas. US ir CA atveju be filtro tai yra valstija, kurios pavadinimas sutampa su srities pavadinimu; jei tokios nėra, naudojama išsaugota srities reikšmė, o jei ir jos nėra, naudojamas kodas, nustatytas pagal srities prefiksų duomenis. Kitų šalių atveju tai yra išsaugota reikšmė, kuri gali būti tuščia. next_function yra 'v3/getprefixes/{uuid}' (filtruojant papildomai pridedama '?state={code}'), kai available yra daugiau nei 0, kitu atveju – 'v3/order/{uuid}'. Sritys, neturinčios nė vieno atitinkančio prefikso, neįtraukiamos. Sritys, turinčios prefiksų, bet neturinčios turimų numerių, grąžinamos su available reikšme 0.

Pavyzdinė atsakymo struktūra; tai nėra realaus laiko paskyros duomenys ar šiuo metu galiojantis kainos pasiūlymas.

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

Klaidos

• 500: msg 'ISO Code parameter is required': isocode nenurodytas arba tuščias. Tai pataisoma užklausos klaida. Atitinkamas HTTP būsenos kodas nenustatomas.
• 404: msg 'Error: no such country': šalies kodas nežinomas. Atitinkamas HTTP būsenos kodas nenustatomas.
• 404: msg 'State filter is only available for US and CA': kitai šaliai perduota netuščia state reikšmė. Atitinkamas HTTP būsenos kodas nenustatomas.
• 404: msg 'Invalid state': state neatitinka nei žinomo tos šalies valstijos kodo, nei žinomo jos pavadinimo. Atitinkamas HTTP būsenos kodas nenustatomas.
• 404: msg 'No areas found': nė viena sritis neatitinka šalies, šaltinio ir valstijos filtrų. Atitinkamas HTTP būsenos kodas nenustatomas.
• 401: autentifikavimo duomenys nepateikti arba autentifikavimas nepavyko. Siunčiama su HTTP būsenos kodu 401.

Prieinamumas ir šalutinis poveikis

• Paieška prieinama tik klientų paskyroms. Ji nieko nerezervuoja, neužsako ir nekeičia.
• available reikšmė yra informacinė ir iki kito veiksmo gali pasikeisti.