Списък на областите на покритие за дадена държава

След като изберете държава (и по желание щат или провинция за САЩ или Канада чрез 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 има информативен характер и може да се промени преди следващата стъпка.