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?Q=Dubai Dental Hospital&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?q=Dubai Dental Hospital&key=YOUR_KEY
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"address_comment": "G Floor",
"address_name": "Dubai Dental Hospital, 34, Dubai Healthcare City street",
"building_name": "Dubai Dental Hospital",
"full_name": "Dubai, Dubai Dental Hospital",
"id": "70000001035848136",
"name": "Dubai, dental clinic",
"purpose_name": "Medical facility",
"type": "branch"
}
],
"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 entrace value):
https://catalog.api.2gis.com/3.0/items?q=Dubai Dental Hospital&type=entrace&key=YOUR_KEY
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 400,
"error": {
"message": "Param 'type' is invalid. Value 'entrace' is outside of allowed values: 'coordinates','station_entrance','street','adm_div.country','route','branch','adm_div.district','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','station','gate','building','station.metro','road','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 or too broad results
Possible issue causes:
No key parameters used
Requests work most efficiently if the following parameters are used:
location: coordinates of the landmark where to search for results (user location, city center, and others). The closer a found object is to the landmark, the higher is stands in the search response.viewpoint1andviewpoint2: coordinates of upper-left and lower-right edges of a rectangular view area. This area serves as one of the criteria for selecting and ranking results but it does not limit the search area severely.radius: search radius in meters to filter the results.type: type of objects considered for search. If multiple types are passed, more relevant results of some types can displace less relevant results of other types.
Example of an efficient request with all key parameters:
https://catalog.api.2gis.com/3.0/items?q=Dubai Dental Hospital&location=55.324961,25.232666&viewpoint1=55.309271, 25.23968&viewpoint2=55.331659, 25.19889&type=branch&radius=300&key=YOUR_KEY
Response
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"address_comment": "G Floor",
"address_name": "Dubai Dental Hospital, 34, Dubai Healthcare City street",
"building_name": "Dubai Dental Hospital",
"full_name": "Dubai, Dubai Dental Hospital",
"id": "70000001035848136",
"name": "Dubai, dental clinic",
"purpose_name": "Medical facility",
"type": "branch"
}
],
"total": 1
}
}
To learn about parameter formats, available values, and limitations, see the API Reference.
Not enough parameter to narrow down the search
Use geographic restrictions and pass 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?q=Dubai Health Care City&key=YOUR_KEY
Response (3 objects are returned)
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"color": "#3EA332",
"full_name": "Dubai, Dubai Health Care City",
"id": "13933797326193949",
"name": "Dubai Health Care City",
"route_type": "metro",
"subtype": "metro",
"type": "station"
},
{
"full_name": "Dubai, Dubai Health Care City",
"id": "70030076480208453",
"name": "Dubai Health Care City",
"subtype": "division",
"type": "adm_div"
},
{
"full_name": "Dubai, Dubai Health Care City",
"id": "13933698541955731",
"name": "Dubai Health Care City",
"subtype": "place",
"type": "adm_div"
}
],
"total": 3
}
}
Example of a request with the type specified:
https://catalog.api.2gis.com/3.0/items?q=Dubai Health Care City&key=YOUR_KEY&type=station
Response (1 object is returned)
{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
"result": {
"items": [
{
"color": "#3EA332",
"full_name": "Dubai, Dubai Health Care City",
"id": "13933797326193949",
"name": "Dubai Health Care City",
"route_type": "metro",
"subtype": "metro",
"type": "station"
}
],
"total": 1
}
}