Решение частых проблем поиска

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

Поиск не даёт результатов

Возможные причины:

Ошибки в параметрах запроса

Убедитесь, что названия параметров написаны в нужном регистре и без опечаток: см. Справочник 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
    }
}

Несуществующие параметры и значения

Проверьте список доступных значений в Справочнике 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
   }
}

Поиск не даёт результатов​

Ошибки в параметрах запроса​

Несуществующие параметры и значения​

Нет данных в 2ГИС​

Неточные координаты​

Не указан населённый пункт​

Поиск даёт неточные или слишком широкие результаты​

Неточный адрес объекта​

Недостаточно параметров для сужения поиска​

Поиск не даёт результатов

Ошибки в параметрах запроса

Несуществующие параметры и значения

Нет данных в 2ГИС

Неточные координаты

Не указан населённый пункт

Поиск даёт неточные или слишком широкие результаты

Неточный адрес объекта

Недостаточно параметров для сужения поиска