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

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

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

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

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

Убедитесь, что имена параметров написаны в нужном регистре и без опечаток: см. Справочник API.

Пример ошибочного запроса (неверный регистр параметра q):

https://catalog.api.2gis.com/3.0/items/geocode?Q=Москва, Садовническая, 25&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 404,
        "error": {
            "message": "Results not found",
            "type": "itemNotFound"
        },
        "issue_date": "20240524"
    }
}

Пример исправленного запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Садовническая, 25&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "address_name": "Садовническая улица, 25",
                "full_name": "Москва, Садовническая улица, 25",
                "id": "4504235282713264",
                "name": "Садовническая улица, 25",
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

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

Проверьте список доступных значений в Справочнике API.

Пример ошибочного запроса (у параметра type не существует значения house):

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.618947&lat=55.752954&type=house&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "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','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','gate','building','adm_div.division','adm_div.living_area'",
            "type": "paramIsOutsideSet"
        },
        "issue_date": "20240524"
    }
}

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

Чтобы убедиться, что данные действительно отсутствуют в 2ГИС, попробуйте найти необходимый объект вручную на карте: откройте сайт https://2gis.ru/ и введите адрес, имя или координаты объекта в строку поиска. Если вы нашли нужный объект, скорректируйте запрос и отправьте снова.

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

Из-за неровности рельефа и погрешностей, координаты одного и того же объекта в разных источниках могут отличаться. Используйте параметр radius для поиска объекта в определённом радиусе от координаты. Рекомендуемое значение — от 300 метров.

Пример запроса без указания радиуса:

https://catalog.api.2gis.com/3.0/items/geocode?lon=36.207245&lat=51.756514&type=building&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 404,
        "error": {
            "message": "Results not found",
            "type": "itemNotFound"
        },
        "issue_date": "20240524"
    }
}

Пример запроса с указанием радиуса:

https://catalog.api.2gis.com/3.0/items/geocode?lon=36.207245&lat=51.756514&type=building&key=YOUR_KEY&radius=200

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "full_name": "Курск, Подземное сооружение",
                "id": "70030076246895032",
                "name": "Подземное сооружение",
                "purpose_name": "Подземное сооружение",
                "type": "building"
            },
            {
                "address_name": "Никитская, 66",
                "full_name": "Курск, Никитская, 66",
                "id": "10274472305106104",
                "name": "Никитская, 66",
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "Островского, 8а",
                "full_name": "Курск, Островского, 8а",
                "id": "10274472305101732",
                "name": "Островского, 8а",
                "purpose_name": "Автосервис",
                "type": "building"
            }
        ],
        "total": 3
    }
}

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

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

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

Если вы запрашиваете точный адрес объекта (с городом, улицей и номером дома), но в поисковой выдаче возвращается не один конкретный объект, а несколько близких, вы можете определить, в каком именно компоненте адреса ошибка. Для этого добавьте к своему запросу параметр 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=YOUR_KEY

Ответ (возвращаются 2 объекта с разной точностью)

{
    "meta": {
        "api_version": "3.0.18331",
        "code": 200,
        "issue_date": "20241125"
    },
    "result": {
        "items": [
            {
                "address_name": "Садовническая улица, 84 ст7",
                "full_name": "Москва, Садовническая улица, 84 ст7",
                "id": "4504235301205672",
                "name": "Садовническая улица, 84 ст7",
                "purpose_name": "Кафе, бар",
                "search_attributes": {
                    "dgis_address_details": {
                        "address": "",
                        "apartment": "",
                        "entrance": "",
                        "precision": "near"
                    }
                },
                "type": "building"
            },
            {
                "full_name": "Москва, Садовническая улица",
                "id": "4504338361749918",
                "name": "Садовническая улица",
                "search_attributes": {
                    "dgis_address_details": {
                        "address": "",
                        "apartment": "",
                        "entrance": "",
                        "precision": "street"
                    }
                },
                "type": "street"
            }
        ],
        "total": 2
    }
}

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

Используйте больше фильтрующих параметров. Например:

Укажите тип объекта, который необходимо найти. Пример запроса без указания типа:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.611915&lat=55.754061&key=YOUR_KEY

Ответ (возвращаются 6 объектов)

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "full_name": "Москва, улица Моховая",
                "id": "4504338361746011",
                "name": "улица Моховая",
                "type": "street"
            },
            {
                "full_name": "Москва, Арбат",
                "id": "4504209512726530",
                "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"
            },
            {
                "full_name": "Москва, Тверской",
                "id": "4504209512726536",
                "name": "Тверской",
                "subtype": "district",
                "type": "adm_div"
            }
        ],
        "total": 6
    }
}

Пример запроса с указанием типа объекта:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.611915&lat=55.754061&key=YOUR_KEY&type=street

Ответ (возвращается 1 объект)

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "full_name": "Москва, улица Моховая",
                "id": "4504338361746011",
                "name": "улица Моховая",
                "type": "street"
            }
        ],
        "total": 1
    }
}

Укажите более конкретное геоограничение. Пример запроса для поиска адреса в деревне:

https://catalog.api.2gis.com/3.0/items/geocode?q=Вологодская область, деревня Кузнецово, 8&fields=items.point&key=YOUR_KEY

Ответ (возвращаются 8 объектов)

{
    "meta": {
        "api_version": "3.0.18209",
        "code": 200,
        "issue_date": "20241115"
    },
    "result": {
        "items": [
            {
                "address_name": "деревня Кузнецово, 8",
                "full_name": "Кузнецово (Архангельское сп), деревня Кузнецово, 8",
                "id": "70030076366218756",
                "name": "деревня Кузнецово, 8",
                "point": {
                    "lat": 59.599014,
                    "lon": 39.949746
                },
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 8",
                "full_name": "Кузнецово (Пригородное сп), деревня Кузнецово, 8",
                "id": "70030076367248181",
                "name": "деревня Кузнецово, 8",
                "point": {
                    "lat": 59.42712,
                    "lon": 40.227485
                },
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 22Б",
                "full_name": "Кузнецово (Югское сп), деревня Кузнецово, 22Б",
                "id": "70030076352491557",
                "name": "деревня Кузнецово, 22Б",
                "point": {
                    "lat": 58.973383,
                    "lon": 38.55934
                },
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 7",
                "full_name": "Кузнецово (Воскресенское сп), деревня Кузнецово, 7",
                "id": "70030076353112253",
                "name": "деревня Кузнецово, 7",
                "point": {
                    "lat": 59.430421,
                    "lon": 37.771886
                },
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 10",
                "full_name": "Кузнецово (Мяксинское сп), деревня Кузнецово, 10",
                "id": "70030076352930640",
                "name": "деревня Кузнецово, 10",
                "point": {
                    "lat": 58.849518,
                    "lon": 38.393843
                },
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 4",
                "full_name": "Кузнецово (Юдинское сп), деревня Кузнецово, 4",
                "id": "70030076654509647",
                "name": "деревня Кузнецово, 4",
                "point": {
                    "lat": 60.900447,
                    "lon": 46.1317
                },
                "purpose_name": "Административное здание",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 22",
                "full_name": "Кузнецово (Заречное сп), деревня Кузнецово, 22",
                "id": "70030076688391346",
                "name": "деревня Кузнецово, 22",
                "point": {
                    "lat": 60.762124,
                    "lon": 46.385865
                },
                "purpose_name": "Частный дом",
                "type": "building"
            },
            {
                "address_name": "деревня Кузнецово, 9",
                "full_name": "Кузнецово, деревня Кузнецово, 9",
                "id": "70030076365894067",
                "name": "деревня Кузнецово, 9",
                "point": {
                    "lat": 59.037984,
                    "lon": 40.251655
                },
                "purpose_name": "Частный дом",
                "type": "building"
            }
        ],
        "total": 8
    }
}

Пример запроса с уточнённым геоограничением (указано сельское поселение, к которому относится деревня):

https://catalog.api.2gis.com/3.0/items/geocode?q=Вологодская область, Пригородное сп, деревня Кузнецово, 8&fields=items.point&key=YOUR_KEY

Ответ (возвращается 1 объект)

{
    "meta": {
        "api_version": "3.0.18209",
        "code": 200,
        "issue_date": "20241115"
    },
    "result": {
        "items": [
            {
                "address_name": "деревня Кузнецово, 8",
                "full_name": "Кузнецово (Пригородное сп), деревня Кузнецово, 8",
                "id": "70030076367248181",
                "name": "деревня Кузнецово, 8",
                "point": {
                    "lat": 59.42712,
                    "lon": 40.227485
                },
                "purpose_name": "Частный дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}