Список штатів США або провінцій Канади з номерами в наявності

Використовуйте цей необов’язковий крок для Сполучених Штатів або Канади, щоб звузити пошук за штатом або провінцією. Приймаються лише 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, якщо хоча б один врахований префікс підтримує мобільний зв’язок; для US завжди 0, якщо для вашого облікового запису не ввімкнено доступ до мобільних номерів США); 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 має інформаційний характер і не закріплює за вами номери.