Списък на щатите в САЩ или канадските провинции с налични номера

Използвайте тази незадължителна стъпка за Съединените щати или Канада, за да стесните търсенето по щат или провинция. Приемат се само 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 има само информативен характер и не задържа номера.