Troubleshooting common search issues

When using the Geocoder API, you might not receive the results you expect. For example, the response might contain too many search results or might not contain the object of your interest. The instruction contains most common search issues and possible solutions to them.

No results are returned

Possible issue causes:

Mistakes in request parameters

Make sure that parameter names are written in the proper case and without typos: see the API Reference.

Incorrect request example (the q parameter is specified in the wrong case as Q):

https://catalog.api.2gis.com/3.0/items/geocode?Q=Moskva, Universitetsky prospekt, 9&key=API_KEY

Response

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

Fixed request example (the q parameter is specified in the correct case):

https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, Universitetsky prospekt, 9&key=API_KEY

Response

{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260810"
    },
    "result": {
        "items": [
            {
                "address_name": "Университетский проспект, 9",
                "full_name": "Москва, Университетский проспект, 9",
                "id": "4504235282606753",
                "name": "Университетский проспект, 9",
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Invalid parameters or values

Check the list of available values in the API Reference.

Incorrect request example (the type parameter does not have a house value):

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&type=house&key=API_KEY

Response

{
    "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"
    }
}

No data in 2GIS

To make sure that 2GIS is indeed missing data, try to find the required object manually. Open the map at 2gis.ru and enter the object address, name, or coordinates in the search field. If you find the required object, edit your request and send it again.

Inaccurate coordinates

Due to uneven terrain and errors, coordinates for the same object may differ in different sources. Use the radius parameter to search for an object within a specified radius of a point.

Example of a request without specifying the radius:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.109256&lat=55.770784&type=building&key=API_KEY

Response

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

Example of a request specifying the radius:

https://catalog.api.2gis.com/3.0/items/geocode?lon=37.109256&lat=55.770784&type=building&radius=100&key=API_KEY

Response

{
    "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
    }
}

No locality specified

If you do not specify a locality, the search may return no results.

Example of a request without specifying the locality:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 8&fields=items.point,items.geometry.centroid&key=API_KEY

Response

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

Example of a request with a specified locality:

https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 8, Moskva&fields=items.point,items.geometry.centroid&key=API_KEY

Response

{
    "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
    }
}

Inaccurate or too broad results

Possible issue causes:

Inaccurate object address

If you request a precise object address (specifying a city, a street, and a building number), but the search results contain not one specific object but several close ones, you can determine, which address component contains a mistake. Add the fields=items.search_attributes.dgis_address_details parameter to your request and send it again. For each element in the response, you get new search_attributes data with the precision field that indicates the precision of the request and response correspondence.

precision	Address in request	Address in response	Comment
exact	Moskva, Sadovnicheskaya ulitsa, 20 st1	Moskva, Sadovnicheskaya ulitsa, 20 st1	The requested object with a correct building number is found.
number	Moskva, Sadovnicheskaya ulitsa, 20	Moskva, Sadovnicheskaya ulitsa, 20 st1	The requested object with a correct building number is found, but a part of the number (e.g. letter) in the request is missing, incorrect, or specified in a wrong format.
near	Moskva, Sadovnicheskaya ulitsa, 85	Moskva, Sadovnicheskaya ulitsa, 84 st7	The requested object is not found (building number or part of it in the request is incorrect), but the one with the closest building number is returned. A building is considered close if its number differs from the requested number by 20 or less.
street	Moskva, Sadovnicheskaya ulitsa, 200	Moskva, Sadovnicheskaya ulitsa	If the result contains only elements with the street precision, it means that the requested object is not found because the building number is incorrect (and no nearest objects are found) or the street name is partially incorrect.
other	Moskva, Semenovsky park, 1	Semenovsky office park	No matches are found for the address, but another object (not an address) with a name similar to the street name is found.

Example of a request with an incorrect building number:

https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, Sadovnicheskaya ulitsa, 85&fields=items.search_attributes.dgis_address_details&key=API_KEY

Response (2 objects with different precision are returned)

{
    "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
    }
}

Not enough parameters to narrow down the search

Use more filtering parameters. For example:

• Specify an object type.

  Example of a request without specifying the type:

  https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&key=API_KEY

  Response (6 objects are returned)

  {
     "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
     }
  }

  
  

  Example of a request with specifying the type:

  https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&type=adm_div.city&key=API_KEY

  Response (1 object is returned)

  {
     "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
     }
  }

• Specify more precise georestriction.

  Example of a request to search for an address in a village:

  https://catalog.api.2gis.com/3.0/items/geocode?q=Vologodskaya oblast, derevnya Kuznetsovo, 10&fields=items.point&key=API_KEY

  Response (4 objects are returned)

  {
     "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
     }
  }

  
  

  Example of a request with a more precise georestriction (the rural settlement to which the village belongs is specified):

  https://catalog.api.2gis.com/3.0/items/geocode?q=Vologodskaya oblast, Prigorodnoye sp, derevnya Kuznetsovo, 10&fields=items.point&key=API_KEY

  Response (1 object is returned)

  {
     "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260810"
     },
     "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
     }
  }