Листа области покривености за земљу

Након што изаберете земљу (а за САД или Канаду, по жељи, и савезну државу или покрајину из резултата getstates), позовите getareas да бисте видели у којим областима се нуде бројеви. Сачувајте uuid области за следећи корак.

Свака област води до једног од два следећа корака:

• available > 0: next_function има вредност v3/getprefixes/{uuid}, уз ?state= који се додаје када филтрирате по савезној држави или покрајини. Користите га за преглед префикса.
• available = 0: област има префиксе, али нема залиха, а next_function има вредност v3/order/{uuid}. У документацији за наручивање погледајте шта је потребно за овај корак.

available представља укупан број за целу област, чак и када филтрирате по савезној држави или покрајини. Овај филтер прихвата ознаку или пун назив, али ради само за US и CA. Ако филтер по савезној држави или покрајини врати No areas found, покушајте поново без њега. Провере се извршавају овим редоследом: недостајућа ознака земље, непозната земља, филтер по савезној држави или покрајини за другу земљу, неважећа савезна држава или покрајина, непостојање одговарајућих области. Сваки од ових случајева враћа код 500 или 404 у status.code, без одговарајућег HTTP статуса.

Захтев

Обавезно: HTTP Basic аутентификација или Bearer токен (погледајте Аутентификација и одговори API-ја). Ако аутентификација не успе, враћа се HTTP 401 пре извршавања претраге.

GET са параметром isocode у путањи и опционим параметрима state и pid у низу упита. Ако се сегмент путање изостави, уместо њега чита се поље 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'

Одговор

Стандардни омотач одговора. У случају успеха, status.code је 200, status.msg је 'Results: N', status.results је N, а response је листа сортирана по називу области. Поља: uuid (идентификатор области чију унутрашњу структуру не треба тумачити, користи се у следећем кораку); country_uuid (идентификатор земље дужине 32 знака чију унутрашњу структуру не треба тумачити, није потребан касније); name; area_type и number_type (каталошки описи; ставке не представљају нужно типове локалних бројева); country_iso; is_mobile (0 или 1, на основу ознака области за мобилне бројеве; увек 0 за US, осим ако је на вашем налогу омогућена употреба мобилних бројева за US); available (укупне залихе свих одговарајућих префикса области, без ограничавања на тражену савезну државу или покрајину); sms_coverage (0 или 1); returns_numbers (0 или 1, највећа вредност ознаке међу префиксима области); latitude и longitude; state_iso; next_function. state_iso: када је задат филтер по савезној држави или покрајини, ово је ознака утврђена на основу филтера. За US и CA без филтера, то је савезна држава или покрајина чији се назив поклапа са називом области; ако таква не постоји, користи се сачувана вредност области, а ако ни она не постоји, ознака изведена из података о префиксима области. За друге земље то је сачувана вредност и може бити празна. next_function је 'v3/getprefixes/{uuid}' (уз додатак '?state={code}' када се користи филтер) када је available веће од 0, а у супротном је 'v3/order/{uuid}'. Области које немају ниједан одговарајући префикс се изостављају. Области које имају префиксе, али немају залиха, враћају се са вредношћу available 0.

Илустрација структуре одговора; не представља податке налога у реалном времену нити актуелну понуду.

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

Грешке

• 500: msg 'ISO Code parameter is required': isocode недостаје или је празан. Ово је грешка у захтеву која се може исправити. Одговарајући HTTP статус се не поставља.
• 404: msg 'Error: no such country': ознака земље је непозната. Одговарајући HTTP статус се не поставља.
• 404: msg 'State filter is only available for US and CA': за другу земљу послата је непразна вредност параметра state. Одговарајући HTTP статус се не поставља.
• 404: msg 'Invalid state': state није ни позната ознака ни познат назив савезне државе или покрајине за ту земљу. Одговарајући HTTP статус се не поставља.
• 404: msg 'No areas found': ниједна област не одговара филтерима за земљу, извор и савезну државу или покрајину. Одговарајући HTTP статус се не поставља.
• 401: Аутентификација недостаје или није успела. Шаље се уз HTTP статус 401.

Доступност и споредни ефекти

• Претрага је доступна само корисничким налозима. Ништа не резервише, не наручује нити мења.
• available је информативна вредност и може се променити пре следећег корака.