Приказ савезних држава САД или канадских покрајина са бројевима на залихама

Користите овај необавезни корак за Сједињене Америчке Државе или Канаду да бисте сузили претрагу на савезну државу или покрајину. Прихватају се само US и CA.

• Свака ставка описује префиксе који су на залихама за ту савезну државу у тренутку захтева.
• Пратите везу next_function да бисте приказали области те савезне државе. Она већ садржи филтер state, али не и pid.
• При претрази области подаци о савезној држави упоређују се на нешто другачији начин. Ако за неку савезну државу next_function врати No areas found, позовите getareas без навођења савезне државе уместо тога.
• Проверите status.code пре читања response. За неподржану земљу или земљу без одговарајућих залиха враћа се код 404 без одговарајућег HTTP статуса.
• Празна листа са кодом 200 значи да залихе постоје, али не садрже податке о савезној држави. Позовите getareas без навођења савезне државе.

Захтев

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

GET са isocode у путањи. Ако се тај сегмент путање изостави, уместо њега чита се поље isocode кодирано у формату обрасца. Необавезни pid шаље се у упитном низу.

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

Одговор

Стандардна омотница одговора. При успеху, status.code је 200, status.msg је празно, а status.results је број ставки. response је листа сортирана по name (без разликовања великих и малих слова), а затим по коду state. Поља: state (код савезне државе или покрајине преузет из података префикса о савезној држави, обично два слова; неуобичајене вредности се прослеђују непромењене); name (назив из каталога или код ако каталог нема назив за њега); country_iso; available (укупна залиха свих пребројаних префикса, увек већа од 0); prefix_count (број пребројаних префикса на залихама); is_mobile (1 ако било који пребројани префикс подржава мобилну телефонију; увек 0 за US осим ако су вашем налогу омогућени мобилни бројеви у САД); sms_coverage (1 ако било који пребројани префикс има SMS покривеност); returns_numbers (1 ако било који пребројани префикс има ознаку за враћање бројева или нема вредност за ту ознаку); next_function ('v3/getareas/{isocode}?state={state}'). Ако постоје префикси на залихама, али ниједан не садржи податке о савезној држави, резултат је status.code 200 са празном листом и status.results 0.

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

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

Грешке

• 500: msg 'ISO Code parameter is required': isocode недостаје или је празно. Ово је грешка у захтеву која се може исправити. Не поставља се одговарајући HTTP статус; прочитајте status.code.
• 404: msg 'getstates is only available for US and CA': било који други код земље. Не поставља се одговарајући HTTP статус.
• 404: msg 'No states found': ниједан префикс на залихама не одговара филтерима земље и извора. Не поставља се одговарајући HTTP статус.
• 401: Аутентификација недостаје или није успела. Шаље се са HTTP статусом 401.

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

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