Teldef API

Базовый URL API:

https://teldef.ru/api/

Форматы ответа

API поддерживает два формата ответа: JSON и XML. Формат задаётся параметром format.

• JSON (по умолчанию), если параметр format не указан или равен json.
• XML, если параметр format равен xml.

Эндпойнт: информация о телефоне

Метод: GET

URL:

https://teldef.ru/api/

Параметры запроса

• phone (обязательный) — номер телефона в международном формате, только цифры, без «+». Пример: 79161234567.
• format (необязательный) — формат ответа:
  • json — ответ в формате JSON (по умолчанию).
  • xml — ответ в формате XML.

Как запросить JSON

https://teldef.ru/api/?phone=79161234567
https://teldef.ru/api/?phone=79161234567&format=json

Как запросить XML

https://teldef.ru/api/?phone=79161234567&format=xml

Структура ответа

Базовые поля

Независимо от формата (JSON/XML) логически возвращаются одни и те же поля.

• success — флаг успешности обработки запроса:
  • true — запрос обработан успешно, данные по номеру найдены.
  • false — произошла ошибка или данные не найдены.
• phone — запрошенный номер телефона в международном формате (только цифры).

Пример базового JSON-ответа

{
  "success": true,
  "phone": "79161234567",
  "country": "RU",
  "operator": "MTS",
  "region": "Moscow",
  "timezone": "Europe/Moscow"
}

Пример базового XML-ответа

<response>
  <success>true</success>
  <phone>79161234567</phone>
  <country>RU</country>
  <operator>MTS</operator>
  <region>Moscow</region>
  <timezone>Europe/Moscow</timezone>
</response>

Расширенные поля ответа

Поля верхнего уровня

• phone — полный номер телефона, по которому выполнен запрос.
• ported — перенесён ли номер (MNP):
  • true — номер перенесён к другому оператору.
  • false — номер обслуживается исходным оператором диапазона.
• ported_operator — название оператора, к которому номер был перенесён (актуальный оператор обслуживания, если ported = true).
• ported_inn — ИНН оператора, к которому номер перенесён.
• range_found — найден ли номерной диапазон:
  • true — диапазон найден.
  • false — диапазон не найден.
• generation_time_sec — время генерации ответа в секундах.
• range — вложенный объект/блок с информацией о номерном диапазоне, к которому относится номер.

Поля внутри блока range

• abc_def — трёхзначный код сети (ABC/DEF), как правило, код оператора (например, 903).
• num_from — начало диапазона абонентских номеров в виде целого числа.
• num_to — конец диапазона абонентских номеров в виде целого числа.
• operator — наименование оператора, которому принадлежит номерной диапазон (по данным реестра диапазонов).
• region — регион, для которого выделен номерной диапазон.
• territory — текстовое описание территории обслуживания (город, область и т.п.).
• capacity — ёмкость диапазона, количество номеров в данном блоке.
• inn — ИНН оператора, которому принадлежит номерной диапазон.

Пример расширенного XML-ответа

<response>
  <phone>79037279104</phone>
  <ported>true</ported>
  <ported_operator>ООО 'Т2 Мобайл'</ported_operator>
  <ported_inn>7743895280</ported_inn>
  <range_found>true</range_found>
  <generation_time_sec>0.001409</generation_time_sec>
  <range>
    <abc_def>903</abc_def>
    <num_from>7000000</num_from>
    <num_to>7999999</num_to>
    <operator>ПАО "ВЫМПЕЛКОМ"</operator>
    <region>Москва и Московская область</region>
    <territory>Город Москва, Московская область</territory>
    <capacity>1000000</capacity>
    <inn>7713076301</inn>
  </range>
</response>

Ошибки

При ошибках API возвращает HTTP-код ошибки и объект с описанием.

Пример ошибки JSON

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "Неверный формат номера телефона"
  }
}

• 400 — параметр phone отсутствует или некорректен.
• 404 — информация по номеру не найдена.
• 500 — внутренняя ошибка сервера.