Geohelper

Схема

При работе с 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).

Авторизация

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

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

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

Локализация

Язык запроса и ответа определяется по GET-параметрам 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 Флаг успешного запроса
language string Язык ответа
error array Response.error
pagination object (ResponsePagination) Данные пагинации
pagination[limit] integer Количество элементов в текущем ответе
pagination[totalCount] integer Общее количество элементов
pagination[currentPage] integer Текущая страница
pagination[totalPageCount] integer Общее количество страниц с ответом

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

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

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

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

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

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

При обращении к 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."
        ]
    }
}