Troubleshooting common search issues
When using search APIs, you might not receive the results you except. For example, the response might contain too many search results or might not contain the object of your interest. This chapter 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 (wrong case of the q parameter):
https://catalog.api.2gis.com/3.0/items/geocode?Q=34, Dubai Healthcare City street&key=YOUR_KEY
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20240524"
}
}
Fixed request example:
https://catalog.api.2gis.com/3.0/items/geocode?q=34, Dubai Healthcare City street&key=YOUR_KEY
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"address_name": "Dubai Dental Hospital, 34, Dubai Healthcare City street",
"building_name": "Dubai Dental Hospital",
"full_name": "Dubai, Dubai Dental Hospital",
"id": "13933647002506643",
"name": "Dubai Dental Hospital",
"purpose_name": "Medical facility",
"type": "building"
}
],
"total": 1
}
}
Wrong parameters or values
Check the list of available parameters and values in the API Reference.
Incorrect request example (the type parameter does not have an house value):
https://catalog.api.2gis.com/3.0/items/geocode?lon=55.324264&lat=25.230493&type=house&key=YOUR_KEY
Response
{
"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"
}
}
No data in Urbi
To make sure that Urbi is indeed missing data, try to find the required object manually. Open the map at https://maps.urbi.ae/ 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 possible errors, coordinates of one and the same object may not be equal in different courses. Use the radius parameter to search for the object within a specified radius. Recommended value is 300 meters or more.
Example of a request without specifying the radius:
https://catalog.api.2gis.com/3.0/items/geocode?lon=55.331659&lat=25.19889&type=building&key=YOUR_KEY
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20240524"
}
}
Example of a request specifying the radius:
https://catalog.api.2gis.com/3.0/items/geocode?lon=55.331659&lat=25.19889&type=building&key=YOUR_KEY&radius=700
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"full_name": "Dubai, Pier",
"id": "13933647002523581",
"name": "Pier",
"purpose_name": "Pier",
"type": "building"
},
{
"full_name": "Dubai, Pier",
"id": "70030076266590069",
"name": "Pier",
"purpose_name": "Pier",
"type": "building"
}
],
"total": 2
}
}
Inaccurate or too broad results
Possible issue causes:
Not enough parameter to narrow down the search
Use more filtering parameters.
For example, you can specify an object type. Example of a request without specifying the type:
https://catalog.api.2gis.com/3.0/items/geocode?lon=55.194605&lat=25.07728&radius=300&key=YOUR_KEY
Response (7 objects are returned)
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"full_name": "Dubai, Jebel Ali Race Course",
"id": "13933698541945541",
"name": "Jebel Ali Race Course",
"subtype": "place",
"type": "adm_div"
},
{
"full_name": "Dubai, Al Thanyah 2",
"id": "13933621232533869",
"name": "Al Thanyah 2",
"subtype": "district",
"type": "adm_div"
},
{
"full_name": "Dubai, Hadaeq Mohammed Bin Rashid",
"id": "13934059319208596",
"name": "Hadaeq Mohammed Bin Rashid",
"subtype": "division",
"type": "adm_div"
},
{
"full_name": "Dubai",
"id": "13933634117435393",
"name": "Dubai",
"subtype": "city",
"type": "adm_div"
},
{
"full_name": "Dubai Emirate",
"id": "70030076147409277",
"name": "Dubai Emirate",
"subtype": "region",
"type": "adm_div"
},
{
"full_name": "Dubai, Utility structure",
"id": "70030076460767902",
"name": "Utility structure",
"purpose_name": "Utility structure",
"type": "building"
},
{
"full_name": "Additional passage/thoroughfare by permit",
"id": "70030076460768742",
"name": "Additional passage/thoroughfare by permit",
"type": "gate"
}
],
"total": 7
}
}
Example of a request with the type specified:
https://catalog.api.2gis.com/3.0/items/geocode?lon=55.194605&lat=25.07728&radius=300&key=YOUR_KEY&&type=gate
Response (1 object is returned)
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"full_name": "Additional passage/thoroughfare by permit",
"id": "70030076460768742",
"name": "Additional passage/thoroughfare by permit",
"type": "gate"
}
],
"total": 1
}
}