API: документация

  1. Структура запроса
  2. Примеры запросов и ответов
  3. Коды ответов сервера
  4. Коды ошибок
  5. Возвращаемые данные
  6. Возвращаемые значения (операторы связи)
  7. Возвращаемые значения (регионы)

Структура запроса

  • {формат} - json или xml
  • {номер телефона} - строка; все символы, кроме цифр будут удалены
  • {API-ключ} - ваш API-ключ, который можно получить, написав нам на admin@kody.su с указанием цели использования API; для тестирования можно использовать ключ test (с ограниченным лимитом)
  • параметры q и key можно передавать как методом POST, так и методом GET

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

JSON

XML

Коды ответов сервера

200запрос прошел успешно
400неверные входные данные (формат, номер)
403превышен лимит запросов или IP заблокирован
500ошибка сервера

Коды ошибок

NUMBER_NOT_SETне передан номер, передайте его в GET или POST-параметре q
FORMAT_NOT_SETнеправильно передан формат, должен быть json или xml; ознакомьтесь с документацией
AUTH_REQUIREDне передан ключ авторизации, передайте его в GET или POST-параметре key
AUTH_FAILEDневерно указан ключ авторизации
LIMIT_EXCEEDEDпревышен лимит запросов
NUMBER_TOO_SHORTномер слишком короткий
NUMBER_TOO_LONGномер слишком длинный
NUMBER_NOT_FOUNDномер не найден в нашей базе данных
UNKNOWN_ERRORнеизвестная ошибка

Возвращаемые данные (общие для запроса)

successпрошел ли запрос валидацию на сервере
  • true - прошел
  • false - не прошел
queryстрока запроса
quotaВаша квота - оставшееся количество запросов для Вашего API-ключа за текущие сутки
error_codeкод ошибки; выдается, если запрос не прошел валидацию (success=false)
error_messageописание ошибки; выдается, если запрос не прошел валидацию (success=false)
numbersномера - объект (json), либо структура тегов (xml) с данными запрашиваемого номера; если запрос прошел валидацию (success=true)

Возвращаемые данные (номера)

Общее для всех запросов

тег numberтег, содержащий данные об одном номере (xml), атрибут id - сам текущий номер
number_currentтекущий номер (json)
number_successуспешен ли запрос по данному номеру
  • true - номер найден и определен
  • false - номер не найден или не определен, а также превышен лимит запросов
number_typeтип номера; выдается, если номер определен и запрос по нему успешен (status=success)
  • 1 - сотовый телефон России
  • 2 - стационарный телефон России
  • 3 - другие номера
error_codeкод ошибки; выдается при ошибке определения номера (number_success=false)
error_messageописание ошибки; выдается при ошибке определения номера (number_success=false)

Для сотовых телефонов России

defdef-код (первые 3 цифры номера)
number7-значный номер (без def-кода)
code_startдиапазон выделенных номеров, начало
code_endдиапазон выделенных номеров, конец
operatorсотовый оператор, сокращенное наименование
operator_fullсотовый оператор, полное наименование
regionрегион
timeпримерный часовой пояс (сдвиг от времени GMT)
bdpnбаза данных перенесенных номеров:
  • false - отсутствует
  • true - присутствует
bdpn_operatorбаза данных перенесенных номеров: оператор (если номер там присутствует)

Для стационарных телефонов России

codeкод населенного пункта
numberномер без кода
cityнаселенный пункт, для номеров 8-800 указано пустое значение
regionрегион
operatorстационарный оператор, сокращенное наименование
operator_fullстационарный оператор, полное наименование
timeчасовой пояс (сдвиг от времени GMT), для номеров 8-800 указано пустое значение

Для других номеров

country_codeкод страны
city_codeкод населенного пункта (если определен)
numberномер
countryстрана
regionрегион (если определен, указан предположительно)
cityнаселенный пункт (если определен)
timeпримерный часовой пояс - сдвиг от времени GMT (если определен)

Возможные значения (операторы связи), на данный момент:

Для сотовых телефонов России - operator

Для сотовых телефонов России - operator_bdpn

Возможные значения (регионы), на данный момент:

По всем вопросам, касающимся работы API, пишите на admin@kody.su. Мы открыты для любых пожеланий и замечаний.