API: документация
- Структура запроса
- Примеры запросов и ответов
- Коды ответов сервера
- Коды ошибок
- Возвращаемые данные
- Возвращаемые значения (операторы связи)
- Возвращаемые значения (регионы)
Структура запроса
- {формат} - 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) |
Для сотовых телефонов России
number_type_str | ru_mobile |
def | def-код (первые 3 цифры номера) |
number | 7-значный номер (без def-кода) |
code_start | диапазон выделенных номеров, начало |
code_end | диапазон выделенных номеров, конец |
operator | сотовый оператор, сокращенное наименование |
operator_full | сотовый оператор, полное наименование |
region | регион |
time | примерный часовой пояс (сдвиг от времени GMT) |
bdpn | база данных перенесенных номеров: - false - отсутствует
- true - присутствует
|
bdpn_operator | база данных перенесенных номеров: оператор (если номер там присутствует) |
Для стационарных телефонов России
number_type_str | ru_fixed |
code | код населенного пункта |
number | номер без кода |
city | населенный пункт, для номеров 8-800 указано пустое значение |
region | регион |
operator | стационарный оператор, сокращенное наименование |
operator_full | стационарный оператор, полное наименование |
time | часовой пояс (сдвиг от времени GMT), для номеров 8-800 указано пустое значение |
Для сотовых телефонов Украины
number_type_str | ua_mobile |
def | def-код (первые 2 цифры номера) |
number | 7-значный номер (без def-кода) |
operator | сотовый оператор, сокращенное наименование |
time | часовой пояс (сдвиг от времени GMT) |
Для других номеров
number_type_str | other |
country_code | код страны |
city_code | код населенного пункта (если определен) |
number | номер |
country | страна |
region | регион (если определен, указан предположительно) |
city | населенный пункт (если определен) |
time | примерный часовой пояс - сдвиг от времени GMT (если определен) |
Возможные значения (операторы связи), на данный момент:
Для сотовых телефонов России - operator
Для сотовых телефонов России - operator_bdpn
Для сотовых телефонов Украины - operator
Возможные значения (регионы), на данный момент:
По всем вопросам, касающимся работы API, пишите на admin@kody.su. Мы открыты для любых пожеланий и замечаний.