• Схема
• Авторизация
• Локализация
• Формат ответа
• Сообщения об ошибках

Схема

При работе с API необходимо использовать версию v1. Запросы необходимо отправлять по адресу:

http://geohelper.info/api/v1/

Все запросы принимаются в кодировке UTF-8. Все данные необходимо отправлять в JSON. Ответ также формируется в JSON-формате.

Данные типа «Дата» указываются в формате Y-m-d (например 2014-03-21), данные типа «Дата/время» — в формате Y-m-d H:i:s (например 2014-03-21 05:14:07).

Количество запросов к сервису ограничено 10 запросами в секунду.

Авторизация

Авторизация производится с помощью API-ключа, который передается в GET|POST-параметре apiKey:

http://geohelper.info/api/v1/countries?apiKey=wyyHw0m2gox6op3Mwlzc5ww7Ga0y2Osr

Подать запрос на получение API-ключа можно на главной странице.

Локализация

Язык запроса и ответа определяется по GET|POST-параметрам locale[lang] и locale[fallbackLang].

locale[lang] задаёт язык, на котором будет сформирован ответ. Параметр locale[fallbackLang] может быть использован для задания резервного языка (используется когда отсутствует название объекта на основном языке).

http://geohelper.info/api/v1/countries?locale%5Blang%5D=uk&locale%5BfallbackLang%5D=ru

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

В ответ на запрос будет возвращен JSON-объект:

{
    "success": true,
    "language": "ru",
    "result": [],
    "pagination": {
        "limit": 50,
        "totalCount": 200,
        "currentPage": 1,
        "totalPageCount": 4
    }
}

Параметр	Тип	Описание
success	boolean	false	Флаг успешного запроса
language	string	false	Язык ответа
result[]	array	false	Результат запроса
error	object	false	Информация об ошибках при выполнении запроса
pagination		false	Данные пагинации
pagination[limit]	integer	false	Количество элементов в текущем ответе
pagination[totalCount]	integer	false	Общее количество элементов
pagination[currentPage]	integer	false	Текущая страница
pagination[totalPageCount]	integer	false	Общее количество страниц с ответом

Постраничная разбивка доступна в запросах с потенциально большим ответом, который разбивается на порции. К таким запросам относятся:

http://geohelper.info/api/v1/regions
http://geohelper.info/api/v1/cities

В данных запросах помимо самого ответа присутствует мета-информация о постраничной разбивке (поле pagination):

"pagination": {
    "limit": 20,
    "totalCount": 200,
    "currentPage": 3,
    "totalPageCount": 10
}

Если ответ состоит более чем из одной страницы, в запросе доступны GET-параметры:

• pagination[page] (по умолчанию равен 1).
• pagination[limit] (по умолчанию равен 20, может принимать занчения: 20, 50, 100).

Сообщения об ошибках

При обращении к API могут допускаться ошибки, о чем система будет сообщать. Возможны следующие виды ошибок.

1) Не указан apiKey:

HTTP/1.1 403 Forbidden

{
    "success": false,
    "error": {
        "message": "\u0022apiKey\u0022 is missing.",
        "code": 403
    }
}

2) Неверный apiKey:

HTTP/1.1 403 Forbidden

{
    "success": false,
    "error": {
        "message": "\u0022apiKey\u0022 is invalid.",
        "code": 403
    }
}

3) API-ключ неактивен:

HTTP/1.1 403 Forbidden

{
    "success": false,
    "error": {
        "message": "\u0022apiKey\u0022 is deactivated.",
        "code": 403
    }
}

4) Некорректные данные в параметрах запроса:

HTTP/1.1 400 Bad Request

{
    "success": false,
    "error": {
        "message": "Validation failed with 2 error(s).",
        "code": 1,
        "details": [
            "locale.lang: Language is not available.",
            "locale.lang: Language is not specified."
        ]
    }
}