Геокодирование (geocode) - API документация сервиса gdegeo

Пример запроса

Для вызова endpoint’а /api/v1/geocode используйте HTTP-POST с передачей параметров через тело запроса. Ниже приведён минимальный пример:

curl -X POST "https://gdegeo.ru/api/v1/geocode" \
     -d "secret_key=01|dS5jNvcL0WBtRqAX5thFzBf9kHsHHOycmZrMWYt3385a3b6&address=улица Воронцово Поле, 11/32с2, Москва, 105062"

Здесь:

secret_key — ваш секретный ключ (получить можно в личном кабинете).
address — полный адрес, по которому необходимо получить координаты.

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

Все параметры передаются в теле POST-запроса

Параметр	Обязательность	Возможные значения	Значение по умолчанию	Описание
`secret_key`	обязательно	—	—	Секретный ключ вашего проекта (получается в личном кабинете).
`address`	обязательно	—	—	Строка — полный адрес (улица, дом, город и т. д.) для геокодирования.
`format`	не обязательно	xml, json, jsonv2, geojson, geocodejson	jsonv2	Формат возвращаемых данных
`limit`	не обязательно		10	Количество возвращаемых мест
`details`	не обязательно		1	Нужен ли расширенный ответ

Пример ответа

Успешный ответ приходит в формате JSON:

Показать пример

{
    "status": true,
    "data": [{
        "place_id": 1642875,
        "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
        "osm_type": "node",
        "osm_id": 8938930306,
        "boundingbox": [
            "55.4233836",
            "55.4234836",
            "37.5298316",
            "37.5299316"
        ],
        "lat": "55.4234336",
        "lon": "37.5298816",
        "display_name": "СДЭК, 6В, улица Клемента Готвальда, Подольск, городской округ Подольск, Московская область, Центральный федеральный округ, 142100, Россия",
        "place_rank": 30,
        "category": "amenity",
        "type": "post_office",
        "importance": 0.7201,
        "address": {
            "amenity": "СДЭК",
            "house_number": "6В",
            "road": "улица Клемента Готвальда",
            "city": "Подольск",
            "house": "городской округ Подольск",
            "state": "Московская область",
            "ISO3166-2-lvl4": "RU-MOS",
            "region": "Центральный федеральный округ",
            "postcode": "142100",
            "country": "Россия",
            "country_code": "ru"
        },
    },
    {
        "place_id": 475051,
        "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
        "osm_type": "node",
        "osm_id": 2077327144,
        "boundingbox": [
            "55.423319",
            "55.423419",
            "37.5291958",
            "37.5292958"
        ],
        "lat": "55.423369",
        "lon": "37.5292458",
        "display_name": "Ашан, 6В, улица Клемента Готвальда, Подольск, городской округ Подольск, Московская область, Центральный федеральный округ, 142100, Россия",
        "place_rank": 30,
        "category": "shop",
        "type": "supermarket",
        "importance": 0.7201,
        "address": {
            "shop": "Ашан",
            "house_number": "6В",
            "road": "улица Клемента Готвальда",
            "city": "Подольск",
            "house": "городской округ Подольск",
            "state": "Московская область",
            "ISO3166-2-lvl4": "RU-MOS",
            "region": "Центральный федеральный округ",
            "postcode": "142100",
            "country": "Россия",
            "country_code": "ru"
        },
    }]
}

Где:

Параметр	Видимость	Описание
`status`	всегда	Статус ответа true или false
`data`	Если запрос успешен	Найденные данные
`place_id`	всегда	Идентификатор места
`licence`	всегда	Лицензия
`osm_type`	всегда	Тип OSM объекта.
`osm_id`	всегда	Идентификатор OSM объекта.
`lat`	всегда	Широта
`lon`	всегда	Долгота
`place_rank`	всегда	Масштаб объекта. 28-30 - номера дома. 26-27 - улица, 25 - площади, фермы, местности, 22-24 - район, 17-21 - пригород, 13-16 - город, 10-12 - область, 5-9 - государство, 4 - страна
`category`	всегда	Категория места
`type`	всегда	Тип места
`importance`	всегда	Важность места. Основное значение важности выводится из значений рейтинга страниц Википедии для места.
`addresstype`	всегда	Тип адреса (village - деревня, tourism - туристическое место, amenity - удобство / тц, leisure - досуг)
`name`	всегда	Название места / района / улицы и т.п.
`display_name`	всегда	Полное наименование адреса
`county`	ситуативно	Район (пример. Белоярский район)
`state`	ситуативно	Субъект (пример. Ханты-Мансийский автономный округ — Югра)
`ISO3166-2-lvl4`	всегда	Международный стандарт коротких и уникальных алфавитно-цифровых геокодов (пример. RU-MOW)
`region`	всегда	Округ (пример. Уральский федеральный округ)
`country`	всегда	Страна (пример. Россия)
`country_code`	всегда	Код страны (пример. ru)
`postcode`	ситуативно	Индекс места (пример. 109012)
`city`	ситуативно	Город (пример. Москва)
`suburb`	ситуативно	Район (пример. Тверской район)
`neighbourhood`	ситуативно	Микрорайон (пример. Китай-город)
`quarter`	ситуативно	Квартал (пример. 4)
`road`	ситуативно	Улица (пример. улица Пушкина)
`house_number`	ситуативно	Номер дома (пример. 6В)
`address_name`	всегда	Название места. Иногда может быть null

Возможные ошибки

При возникновении ошибки API вернёт JSON-объект вида:

{
    "status": "error",
    "message": "В запросе отсутствует секретный ключ"
}

Где:

status — статус true или false.
message — текст ошибки

Код ответа	Сообщение	Описание
`400`	В запросе отсутствует секретный ключ!	В запросе отсутствует параметр secret_key (широта). Для исправления укажите этот параметр.
`401`	Секретный ключ не верен!	В ключе ошибка или он не верен. Перепроверьте свой ключ, или перегенерируйте в кабинете проекта.
`403`	У вас нет активного тарифа.	Вероятно не оплачен тариф
`404`	Ничего не найдено	По искомому запросу ничего не нашлось
`424`	Не передан искомый адрес (address)	В запросе отсутствует параметр address (адрес). Для исправления укажите этот параметр.