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:
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 |
Requested address | Returned address | Comment |
|---|---|---|---|
exact |
Dubai, Al Mustaqbal street, 1 | 1, Al Mustaqbal street | The requested object with a correct building number is found. |
number |
Dubai, Al Mustaqbal street, 11b | 11a, Al Mustaqbal street | 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 |
Dubai, Al Mustaqbal street, 13 | 15b, Al Mustaqbal street | 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 |
Dubai, Sheikh Zayed road, 1040 | Sheikh Zayed road, Dubai | 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 |
Dubai, Al Mustaqbal street, 1000 | Dubai, Mustaqbal Street Parking | No matches are found for the address, but another object (not an address) with a name similar to the street name is found. |
Request example with an incorrect building number:
https://catalog.api.2gis.com/3.0/items/geocode?q=Dubai, Al Mustaqbal street, 144&fields=items.search_attributes.dgis_address_details&key=YOUR_KEY
Response (two objects with different precision are returned)
{
"meta": {
"api_version": "3.0.18331",
"code": 200,
"issue_date": "20241125"
},
"result": {
"items": [
{
"address_name": "Iris Bay Tower, 145, Al Mustaqbal street",
"building_name": "Iris Bay Tower",
"full_name": "Dubai, Iris Bay Tower",
"id": "13933647002592293",
"name": "Iris Bay Tower",
"purpose_name": "Commercial building",
"search_attributes": {
"dgis_address_details": {
"address": "",
"apartment": "",
"entrance": "",
"precision": "near"
}
},
"type": "building"
},
{
"full_name": "Al Mustaqbal street, Dubai",
"id": "13933750081562676",
"name": "Al Mustaqbal street",
"search_attributes": {
"dgis_address_details": {
"address": "",
"apartment": "",
"entrance": "",
"precision": "street"
}
},
"type": "street"
}
],
"total": 2
}
}
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
}
}