Список штатов США или провинций Канады с номерами в наличии

Используйте этот необязательный шаг для США или Канады, чтобы сузить поиск до штата или провинции. Допускаются только 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 носит информационный характер и не закрепляет за вами номера.