Обзор
Geocoder API позволяет преобразовывать координаты объекта в адрес и наоборот, адрес в координаты.
Пример работы
Кликните на карту, чтобы узнать адрес объекта.
Нажмите на карту, чтобы увидеть URL запроса к API
Вы также можете поработать с Geocoder API в песочнице внутри личного кабинета (авторизация не требуется).
Основные возможности
Вы можете использовать:
- Прямое геокодирование: определить координаты объекта по его адресу. Например, вы можете указать адрес доставки на карте и получить координаты объекта: запрос
Москва, улица Каретный ряд, 3, ст1вернёт координаты55.770784, 37.609256. - Обратное геокодирование: определить адрес объекта по его координатам. Например, вы можете указать точку на карте и получить адрес здания, ближайшего к этой точке: запрос
55.770784, 37.609256вернёт адресМосква, улица Каретный ряд, 3 ст1.
Также вы можете обрабатывать результаты поиска: сортировать их, получать нужную страницу и т. д. Подробнее о каждом параметре см. в Справочнике API и в разделе Примеры.
Изучите возможности других API поиска и дополните ваши сценарии работы с объектами на карте. Например, чтобы формировать подсказки при поиске объектов, используйте Suggest API. Если вы хотите создать поисковый виджет на карте, изучите готовый пример интеграции поисковых API в веб-приложение.
Дополнительная информация по запросу
Получение некоторой информации об объектах доступно только по запросу и за дополнительную плату. Чтобы приобрести доступ к полям ниже, свяжитесь с отделом продаж 2ГИС.
Поля (указываются с помощью параметра fields):
items.contact_groups— контакты компании;items.floors— количество этажей;items.floor_plans— планы этажей;items.links.database_entrances.apartments_info— информация о квартирах в доме;items.employees_org_count— численность сотрудников организации;items.itin— индивидуальный номер налогоплательщика;items.trade_license— торговая лицензия филиала;items.fias_code— код ФИАС улиц и административных территорий;items.address.components.fias_code— код ФИАС зданий;items.fns_code— код ФНС административных территорий;items.okato— код ОКАТО улиц и административных территорий;items.address.components.okato— код ОКАТО зданий;items.oktmo— код ОКТМО улиц и административных территорий;items.address.components.oktmo— код ОКТМО зданий;items.structure_info.material— материал здания;items.structure_info.apartments_count— количество квартир;items.structure_info.porch_count— количество подъездов;items.structure_info.floor_type— тип перекрытий в здании;items.structure_info.gas_type— тип газоснабжения здания;items.structure_info.year_of_construction— год постройки здания;items.structure_info.elevators_count— количество лифтов в здании;items.structure_info.is_in_emergency_state— факт признания дома аварийным;items.structure_info.project_type— серия или проект постройки здания;items.structure_info.chs_name— название объекта культурного наследия;items.structure_info.chs_category— категория объекта культурного наследия.
Начало работы
Выполните шаги ниже, чтобы познакомиться с возможностями Geocoder API и отправить запросы на поиск объектов по адресу и координатам.
Получение ключа доступа
-
Зарегистрируйтесь в личном кабинете Менеджер Платформы.
-
Создайте демо-ключ или купите подписку для доступа к API. Подробнее о стоимости сервиса см. в разделе Тарифы.
Данные по запросуДля получения некоторой информации об объектах требуется дополнительное согласование. Изучите список полей для получения дополнительной информации по запросу.
Подробнее о работе с ключами и подписками см. в документации личного кабинета.
Используйте MCP-сервер 2ГИС для доступа к геоданным при работе с AI-агентами.
Пример запроса
Прямое геокодирование
Запрос к Geocoder API для прямого геокодирования должен содержать:
- Адрес объекта, координаты которого нужно получить. Для повышения точности поиска укажите населённый пункт или регион в текстовом запросе или другое геоограничение поиска. Подробнее см. в инструкции Поиск по адресу.
- Поле
fields=items.point,items.geometry.centroidдля получения координат объекта в ответе. - Ваш API-ключ.
Чтобы получить координаты объекта по его адресу, отправьте GET-запрос к /3.0/items/geocode:
https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, улица Каретный ряд, 3&fields=items.point,items.geometry.centroid&key=API_KEY
В запросе укажите:
q=Москва, улица Каретный ряд, 3— текстовый запрос для поиска объекта по адресу.fields=items.point,items.geometry.centroid— включает в ответ поля с координатами объекта.key=API_KEY— значение API-ключа.
Обратное геокодирование
Запрос к Geocoder API для обратного геокодирования должен содержать:
- Координаты точки, адрес которой нужно получить.
- Поле
fields=items.adm_div,items.addressдля получения в ответе адреса объекта и административных единиц, которым он принадлежит. - Ваш API-ключ.
Чтобы получить адрес объекта по его координатам, отправьте GET-запрос к /3.0/items/geocode:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609484&lat=55.770763&fields=items.adm_div,items.address&key=API_KEY
В запросе укажите:
lon=37.609484— долгота точки.lat=55.770763— широта точки.fields=items.adm_div,items.address— включает в ответ поля с административными единицами и адресом объекта.key=API_KEY— значение API-ключа.
Пример ответа
Ответы на запросы возвращаются в формате JSON.
Прямое геокодирование
Пример ответа:
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address_name": "улица Каретный Ряд, 3 ст1",
"full_name": "Москва, улица Каретный Ряд, 3 ст1",
"geometry": {
"centroid": "POINT(37.609256 55.770784)"
},
"id": "4504235282731438",
"name": "улица Каретный Ряд, 3 ст1",
"point": {
"lat": 55.770784,
"lon": 37.609256
},
"purpose_name": "Культурно-развлекательный комплекс",
"type": "building"
}
],
"total": 1
}
}
Где:
-
result.items— массив объектов, соответствующих запросу. Каждый объект содержит:address_name— адрес объекта.full_name— полное название объекта.geometry.centroid— координаты центра объекта.id— ID объекта.name— название объекта.point— координаты объекта.purpose_name— назначение объекта.type— тип объекта.
-
result.total— общее количество объектов, соответствующих запросу.
Чтобы получить в ответе дополнительные поля, укажите их в параметре fields запроса. Подробнее о каждом параметре см. в Справочнике API.
Обратное геокодирование
Пример ответа:
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address": {
"building_id": "4504235282731438",
"components": [
{
"number": "3 ст1",
"street": "улица Каретный Ряд",
"street_id": "4504338361748615",
"type": "street_number"
}
],
"landmark_name": "сад Эрмитаж",
"postcode": "127006"
},
"address_name": "улица Каретный Ряд, 3 ст1",
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
},
{
"id": "4504209512726536",
"name": "Тверской",
"type": "district"
}
],
"full_name": "Москва, улица Каретный Ряд, 3 ст1",
"id": "4504235282731438",
"name": "улица Каретный Ряд, 3 ст1",
"purpose_name": "Культурно-развлекательный комплекс",
"type": "building"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
}
],
"full_name": "Москва, Сад Эрмитаж",
"id": "4504286822140845",
"name": "Сад Эрмитаж",
"subtype": "place",
"type": "adm_div"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
}
],
"full_name": "Москва, Тверской",
"id": "4504209512726536",
"name": "Тверской",
"subtype": "district",
"type": "adm_div"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
}
],
"full_name": "Москва, Центральный административный округ",
"id": "4504647599390721",
"name": "Центральный административный округ",
"subtype": "division",
"type": "adm_div"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
}
],
"full_name": "Москва",
"id": "4504222397630173",
"name": "Москва",
"subtype": "city",
"type": "adm_div"
},
{
"full_name": "Москва город федерального значения",
"id": "5349042514588558",
"name": "Москва город федерального значения",
"subtype": "region",
"type": "adm_div"
}
],
"total": 6
}
}
Где:
-
result.items— массив объектов, соответствующих запросу. Каждый объект содержит:-
address— адрес объекта:building_id— ID здания.components— массив компонентов адреса объекта.landmark_name— название достопримечательностей, расположенных рядом с объектом.postcode— почтовый индекс объекта.
-
address_name— адрес объекта. -
adm_div— административные деления, которым принадлежит адрес объекта. -
full_name— полное название объекта. -
id— ID объекта. -
name— название объекта. -
purpose_name— назначение объекта. -
subtype— подтип объекта. -
type— тип объекта.
-
-
result.total— общее количество объектов, соответствующих запросу.
Чтобы получить в ответе дополнительные поля, укажите их в параметре fields запроса. Подробнее о каждом параметре см. в Справочнике API.
Тарифы и лимиты
-
Стоимость сервиса рассчитывается исходя из количества успешных запросов в месяц. Успешным запросом к API считается запрос, который возвращает HTTP-код 200 в поле
meta.codeв теле ответа, например:{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
...
} -
Для демо-ключей и ключей, созданных в рамках подписки, действуют лимиты на использование сервиса.
-
Актуальную стоимость и лимиты см. в инструкции Тарифы.
Варианты размещения
- Облако: все актуальные методы Geocoder API доступны через публичные endpoint-ы 2ГИС.
- On-Premise: при установке API-платформы 2ГИС в закрытом контуре доступны все актуальные методы Geocoder API, кроме геокодирования по IP-адресу (/3.0/items/geocode/byip). Подробнее см. в разделе API-платформа для сервера.
Методы, отмеченные как deprecated, устарели и не поддерживаются в обоих вариантах размещения.
Помощь
-
Если у вас возникли вопросы при работе с API, задайте их AI-ассистенту (в правом нижнем углу сайта), воспользуйтесь поиском по документации или отправьте электронное письмо на api@2gis.ru.
-
Если вы хотите обсудить возможности API или его интеграцию с вашим продуктом, обратитесь к менеджеру.
Что дальше?
- Примеры работы Geocoder API.
- Справочник API.