Troubleshooting common search issues
When using Geocoder API, you may occasionally fail to find the object you are looking for, or you might receive inaccurate or overly broad results. This instruction covers common search issues and their possible solutions.
Error codes
The server will return a 200 status code even if the request contains an error. You can find the specific error code in the meta.code field within the response body, for example:
{
"meta": {
"api_version": "3.0.21070",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260806"
}
}
| Code | Description | Solution |
|---|---|---|
| 400 | Invalid request. | Check the error description in the error.message parameter and verify your request parameters. For examples of invalid requests, see the No results are returned section. |
| 403 | Access denied. | In the Platform Manager, ensure that:
|
| 404 | Object not found. | Verify that the request parameters are specified correctly. For an example of an invalid request, see the No results are returned section. |
| 408 | Request timed out. | Retry the request later. |
| 503 | Internal server error. | Retry the request later. |
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
}
}
No access to fields available on demand
If you request information about fields that are available only for an extra cost, ensure that you have access to them. If you do not, the requested fields will not be included in the response body. To purchase access, contact the 2GIS sales team. For more details, see the Additional information on demand section.
Incorrect request example (access is missing for the items.structure_info.year_of_construction field):
https://catalog.api.2gis.com/3.0/items/geocode?q=ulitsa Karetny Ryad, 3, Moskva&fields=items.point,items.structure_info.year_of_construction,&key=API_KEY
The response will not include the field for the building's year of construction:
Response
{
"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
}
}
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_KEYResponse (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_KEYResponse (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_KEYResponse (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_KEYResponse (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}}