Решение частых проблем поиска
При использовании Geocoder API вы можете не найти интересующий вас объект, а также получить неточные или слишком широкие результаты. В инструкции собраны частые проблемы поиска и возможные пути их решения.
Коды ошибок
Сервер будет возвращать код 200, даже если в запросе ошибка. Смотрите код ошибки в поле meta.code в теле ответа, например:
{
"meta": {
"api_version": "3.0.21070",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260806"
}
}
| Код | Описание | Решение |
|---|---|---|
| 400 | Некорректный запрос. | Посмотрите описание ошибки в параметре error.message и проверьте параметры запроса. Примеры ошибочных запросов см. в разделе Поиск не даёт результатов. |
| 403 | Доступ запрещён. | В личном кабинете проверьте, что:
|
| 404 | Объект не найден. | Убедитесь, что параметры запроса указаны без ошибок. Пример ошибочного запроса см. в разделе Поиск не даёт результатов. |
| 408 | Превышено время ожидания. | Повторите запрос позже. |
| 503 | Внутренняя ошибка сервера. | Повторите запрос позже. |
Поиск не даёт результатов
Возможные причины:
Ошибки в параметрах запроса
Убедитесь, что названия параметров написаны в нужном регистре и без опечаток: см. Справочник API.
Пример ошибочного запроса (параметр q указан в неверном регистре как Q):
https://catalog.api.2gis.com/3.0/items/geocode?Q=Москва, Университетский проспект, 9&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21070",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260806"
}
}
Пример исправленного запроса (параметр q указан в правильном регистре):
https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Университетский проспект, 9&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address_name": "Университетский проспект, 9",
"full_name": "Москва, Университетский проспект, 9",
"id": "4504235282606753",
"name": "Университетский проспект, 9",
"purpose_name": "Жилой дом",
"type": "building"
}
],
"total": 1
}
}
Нет доступа к полям по запросу
Если вы запрашиваете информацию о полях, которые доступны за дополнительную плату, убедитесь, что у вас есть к ним доступ. Если доступа нет, эти поля не отобразятся в теле ответа. Чтобы получить доступ, свяжитесь с отделом продаж 2ГИС. Подробнее см. в разделе Дополнительная информация по запросу.
Пример ошибочного запроса (нет доступа к полю items.structure_info.year_of_construction):
https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3, Москва&fields=items.point,items.structure_info.year_of_construction,&key=API_KEY
В ответе не отобразится поле с годом постройки здания:
Ответ
{
"meta": {
"api_version": "3.0.21981",
"code": 200,
"issue_date": "20261106"
},
"result": {
"items": [
{
"address_name": "улица Каретный Ряд, 3 ст1",
"building_name": "Здание театра Эрмитаж",
"full_name": "Москва, улица Каретный Ряд, 3 ст1",
"id": "4504235282731438",
"name": "улица Каретный Ряд, 3 ст1",
"point": {
"lat": 55.770784,
"lon": 37.609256
},
"purpose_name": "Культурно-развлекательный комплекс",
"type": "building"
},
{
"address_name": "улица Каретный Ряд, 3 ст2",
"building_name": "Московский театр Новая Опера им. Е. В. Колобова",
"full_name": "Москва, Московский театр Новая Опера им. Е. В. Колобова",
"id": "4504235282985428",
"name": "Московский театр Новая Опера им. Е. В. Колобова",
"point": {
"lat": 55.771417,
"lon": 37.60928
},
"purpose_name": "Культурное учреждение",
"type": "building"
},
{
"address_name": "улица Каретный Ряд, 3 ст3",
"building_name": "Сфера, Московский драматический театр",
"full_name": "Москва, Сфера, Московский драматический театр",
"id": "4504235282731459",
"name": "Сфера, Московский драматический театр",
"point": {
"lat": 55.770601,
"lon": 37.608629
},
"purpose_name": "Культурное учреждение",
"type": "building"
}
],
"total": 3
}
}
Несуществующие параметры и значения
Проверьте список доступных значений в Справочнике API.
Пример ошибочного запроса (у параметра type не существует значения house):
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&type=house&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21070",
"code": 400,
"error": {
"message": "Param 'type' is invalid. Value 'house' is outside of allowed values: 'coordinates','station_entrance','street','adm_div.country','adm_div.district','adm_div.amana','road','attraction','adm_div.region','adm_div.place','adm_div','parking','adm_div.city','adm_div.district_area','station_platform','crossroad','kilometer_road_sign','adm_div.settlement','coordinates_additional','gate','building','adm_div.division','adm_div.living_area'",
"type": "paramIsOutsideSet"
},
"issue_date": "20260806"
}
}
Нет данных в 2ГИС
Чтобы убедиться, что данные действительно отсутствуют в 2ГИС, попробуйте найти необходимый объект вручную на карте. Откройте карту на 2gis.ru и введите адрес, имя или координаты объекта в строке поиска. Если вы нашли нужный объект, скорректируйте запрос и отправьте снова.
Неточные координаты
Из-за неровности рельефа и погрешностей координаты одного и того же объекта в разных источниках могут отличаться. Используйте параметр radius для поиска объекта в определённом радиусе от точки.
Пример запроса без указания радиуса:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.109256&lat=55.770784&type=building&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21070",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260806"
}
}
Пример запроса с указанием радиуса:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.109256&lat=55.770784&type=building&radius=100&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address_name": "Тимошкино деревня, 8",
"full_name": "Тимошкино, Тимошкино деревня, 8",
"id": "70030076278048903",
"name": "Тимошкино деревня, 8",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 6",
"full_name": "Тимошкино, Тимошкино деревня, 6",
"id": "70030076278048913",
"name": "Тимошкино деревня, 6",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 10",
"full_name": "Тимошкино, Тимошкино деревня, 10",
"id": "70030076278048911",
"name": "Тимошкино деревня, 10",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 4",
"full_name": "Тимошкино, Тимошкино деревня, 4",
"id": "70030076278048902",
"name": "Тимошкино деревня, 4",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 7",
"full_name": "Тимошкино, Тимошкино деревня, 7",
"id": "70030076278048870",
"name": "Тимошкино деревня, 7",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 7а",
"full_name": "Тимошкино, Тимошкино деревня, 7а",
"id": "70030076278048863",
"name": "Тимошкино деревня, 7а",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 14",
"full_name": "Тимошкино, Тимошкино деревня, 14",
"id": "70030076278048909",
"name": "Тимошкино деревня, 14",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 12",
"full_name": "Тимошкино, Тимошкино деревня, 12",
"id": "70030076278048944",
"name": "Тимошкино деревня, 12",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 5а",
"full_name": "Тимошкино, Тимошкино деревня, 5а",
"id": "70030076284062861",
"name": "Тимошкино деревня, 5а",
"purpose_name": "Частный дом",
"type": "building"
},
{
"address_name": "Тимошкино деревня, 9",
"full_name": "Тимошкино, Тимошкино деревня, 9",
"id": "70030076278048871",
"name": "Тимошкино деревня, 9",
"purpose_name": "Частный дом",
"type": "building"
}
],
"total": 20
}
}
Не указан населённый пункт
Если вы не укажете населённый пункт, поиск может не дать результатов.
Пример запроса без указания населённого пункта:
https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 8&fields=items.point,items.geometry.centroid&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21070",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260806"
}
}
Пример запроса с указанным населённым пунктом:
https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 8, Москва&fields=items.point,items.geometry.centroid&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.21263",
"code": 200,
"issue_date": "20260821"
},
"result": {
"items": [
{
"address_name": "улица Каретный Ряд, 8",
"building_name": "Доходный дом Муратова с лавками",
"full_name": "Москва, улица Каретный Ряд, 8",
"geometry": {
"centroid": "POINT(37.610005 55.772626)"
},
"id": "4504235282738212",
"name": "улица Каретный Ряд, 8",
"point": {
"lat": 55.772626,
"lon": 37.610005
},
"purpose_name": "Административное здание",
"type": "building"
}
],
"total": 1
}
}
Поиск даёт неточные или слишком широкие результаты
Возможные причины:
Неточный адрес объекта
Если вы запрашиваете точный адрес объекта (с городом, улицей и номером дома), но в поисковой выдаче возвращается не один конкретный объект, а несколько близких, вы можете определить, в каком именно компоненте адреса ошибка. Для этого добавьте к запросу параметр fields=items.search_attributes.dgis_address_details и отправьте его снова. Для каждого элемента в ответе вы получите новые данные search_attributes с полем precision, которое укажет на точность соответствия запроса и результата.
precision | Адрес в запросе | Адрес в ответе | Комментарий |
|---|---|---|---|
exact | Москва, Садовническая улица, 20 ст1 | Москва, Садовническая улица, 20 ст1 | Найден объект с нужным номером дома и номером строения/корпуса. |
number | Москва, Садовническая улица, 20 | Москва, Садовническая улица, 20 ст1 | Найден объект с нужным номером дома, но в запросе номер строения/корпуса не указан, указан неточно или в неверном формате. |
near | Москва, Садовническая улица, 85 | Москва, Садовническая улица, 84 ст7 | Объект с нужным номером дома или номером строения/корпуса не найден (в запросе неверно указан номер дома, строения или корпуса), но найден ближайший по номеру объект. Дом считается близким, если его номер отличается от запрашиваемого на 20 или меньше. |
street | Москва, Садовническая улица, 200 | Москва, Садовническая улица | Если в ответе возвращаются элементы только с точностью street, это значит, что объект не найден, так как в запросе указан неверный номер дома (и при этом не найдены близлежащие объекты) или указано неполное название улицы (например, без «Верхняя/Нижняя»). |
other | Москва, Семеновский парк, 1 | Семёновский офис-парк | Совпадений по адресу не найдено, по названию улицы найден другой объект с похожим названием (не адрес). |
Пример запроса с несуществующим номером дома:
https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Садовническая улица, 85&fields=items.search_attributes.dgis_address_details&key=API_KEY
Ответ (возвращаются 2 объекта с разной точностью)
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"full_name": "Москва, Садовническая улица",
"id": "4504338361749918",
"name": "Садовническая улица",
"type": "street"
},
{
"address_name": "Садовническая улица, 84 ст7",
"full_name": "Москва, Садовническая улица, 84 ст7",
"id": "4504235301205672",
"name": "Садовническая улица, 84 ст7",
"purpose_name": "Кафе, бар",
"search_attributes": {
"dgis_address_details": {
"address": "84 ст7",
"apartment": "",
"entrance": "",
"precision": "near"
}
},
"type": "building"
}
],
"total": 2
}
}
Недостаточно параметров для сужения поиска
Используйте больше фильтрующих параметров. Например:
-
Укажите тип объекта.
Пример запроса без указания типа:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&key=API_KEYОтвет (возвращаются 6 объектов)
{"meta": {"api_version": "3.0.21070","code": 200,"issue_date": "20260806"},"result": {"items": [{"address_name": "улица Каретный Ряд, 3 ст1","full_name": "Москва, улица Каретный Ряд, 3 ст1","id": "4504235282731438","name": "улица Каретный Ряд, 3 ст1","purpose_name": "Культурно-развлекательный комплекс","type": "building"},{"full_name": "Москва, Сад Эрмитаж","id": "4504286822140845","name": "Сад Эрмитаж","subtype": "place","type": "adm_div"},{"full_name": "Москва, Тверской","id": "4504209512726536","name": "Тверской","subtype": "district","type": "adm_div"},{"full_name": "Москва, Центральный административный округ","id": "4504647599390721","name": "Центральный административный округ","subtype": "division","type": "adm_div"},{"full_name": "Москва","id": "4504222397630173","name": "Москва","subtype": "city","type": "adm_div"},{"full_name": "Москва город федерального значения","id": "5349042514588558","name": "Москва город федерального значения","subtype": "region","type": "adm_div"}],"total": 6}}
Пример запроса с указанием типа объекта:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&type=adm_div.city&key=API_KEYОтвет (возвращается 1 объект)
{"meta": {"api_version": "3.0.21070","code": 200,"issue_date": "20260806"},"result": {"items": [{"full_name": "Москва","id": "4504222397630173","name": "Москва","subtype": "city","type": "adm_div"}],"total": 1}} -
Укажите более точное геоограничение.
Пример запроса для поиска адреса в деревне:
https://catalog.api.2gis.com/3.0/items/geocode?q=Вологодская область, деревня Кузнецово, 10&fields=items.point&key=API_KEYОтвет (возвращаются 4 объекта)
{"meta": {"api_version": "3.0.21070","code": 200,"issue_date": "20260806"},"result": {"items": [{"address_name": "деревня Кузнецово, 10","full_name": "Кузнецово (Мяксинское сп), деревня Кузнецово, 10","id": "70030076352930640","name": "деревня Кузнецово, 10","point": {"lat": 58.849518,"lon": 38.393843},"purpose_name": "Частный дом","type": "building"},{"address_name": "деревня Кузнецово, 10","full_name": "Кузнецово (Пригородное сп), деревня Кузнецово, 10","id": "70030076367268073","name": "деревня Кузнецово, 10","point": {"lat": 59.426913,"lon": 40.227741},"purpose_name": "Частный дом","type": "building"},{"address_name": "Кузнецово деревня, 10","full_name": "Кузнецово, Кузнецово деревня, 10","id": "70030076683308817","name": "Кузнецово деревня, 10","point": {"lat": 59.712673,"lon": 45.392091},"purpose_name": "Частный дом","type": "building"},{"address_name": "деревня Кузнецово (Богородское сп), 10","full_name": "Кузнецово (Богородское сп), деревня Кузнецово (Богородское сп), 10","id": "70030076684512405","name": "деревня Кузнецово (Богородское сп), 10","point": {"lat": 59.990726,"lon": 39.283668},"purpose_name": "Частный дом","type": "building"}],"total": 4}}
Пример запроса с уточнённым геоограничением (указано сельское поселение, к которому относится деревня):
https://catalog.api.2gis.com/3.0/items/geocode?q=Вологодская область, Пригородное сп, деревня Кузнецово, 10&fields=items.point&key=API_KEYОтвет (возвращается 1 объект)
{"meta": {"api_version": "3.0.21070","code": 200,"issue_date": "20260806"},"result": {"items": [{"address_name": "деревня Кузнецово, 10","full_name": "Кузнецово (Пригородное сп), деревня Кузнецово, 10","id": "70030076367268073","name": "деревня Кузнецово, 10","point": {"lat": 59.426913,"lon": 40.227741},"purpose_name": "Частный дом","type": "building"}],"total": 1}}