Skip to main content

Troubleshooting common search issues

When using Places 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?Q=Universitetsky prospekt, 9 Moscow&key=API_KEY
Response
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 404,
        "error": {
            "message": "Results not found",
            "type": "itemNotFound"
        },
        "issue_date": "20260717"
    }
}

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

https://catalog.api.2gis.com/3.0/items?q=Universitetsky prospekt, 9 Moscow&key=API_KEY
Response
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260717"
    },
    "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 parameters and values in the API Reference.

Incorrect request example (the type parameter does not have an entrance value):

https://catalog.api.2gis.com/3.0/items?q=Universitetsky prospekt, 9 Moscow&type=entrance&key=API_KEY
Response
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 400,
        "error": {
            "message": "Param 'type' is invalid. Value 'entrance' is outside of allowed values: 'coordinates','station_entrance','street','adm_div.country','route','branch','adm_div.district','adm_div.amana','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','coordinates_additional','gate','building','station.metro','road','adm_div.division','adm_div.living_area'",
            "type": "paramIsOutsideSet"
        },
        "issue_date": "20260717"
    }
}

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 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 point where to search for results (user location, city center, and others). The closer a found object is to the point, the higher it stands in the search response.
  • viewpoint1 and viewpoint2 - 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.

For more information about the request structure, see the Request example.

Example of an efficient request with all key parameters:

https://catalog.api.2gis.com/3.0/items?q=Universitetsky prospekt, 9 Moscow&type=building&location=37.549425,55.697848&radius=300&viewpoint1=37.531115,55.702856&viewpoint2=37.575258,55.687182&key=API_KEY
Response
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260717"
    },
    "result": {
        "items": [
            {
                "address_name": "Университетский проспект, 9",
                "full_name": "Москва, Университетский проспект, 9",
                "id": "4504235282606753",
                "name": "Университетский проспект, 9",
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

See parameter formats, available values, and limitations in the API Reference.

Not enough parameters to narrow down the search​

Use georestrictions and specify more filtering parameters.

For example, you can specify a category. Example of a request without specifying the category:

https://catalog.api.2gis.com/3.0/items?q=1913 year&location=30.3079,59.9289&key=API_KEY
Response (2 objects are returned)
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260715"
    },
    "result": {
        "items": [
            {
                "address_comment": "1-4 этаж",
                "address_name": "Вознесенский проспект, 13",
                "id": "5348553838538209",
                "name": "1913 год, гостиница",
                "type": "branch"
            },
            {
                "address_comment": "1, 2 этаж",
                "address_name": "Вознесенский проспект, 13",
                "id": "5348552838519391",
                "name": "1913 год, ресторан в историческом центре",
                "type": "branch"
            }
        ],
        "total": 2
    }
}

Example of a request with the specified category:

https://catalog.api.2gis.com/3.0/items?q=1913 year&location=30.3079,59.9289&rubric_id=164&key=API_KEY
Response (1 object is returned)
{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260717"
    },
    "result": {
        "items": [
            {
                "address_comment": "1, 2 этаж",
                "address_name": "Вознесенский проспект, 13",
                "id": "5348552838519391",
                "name": "1913 год, ресторан в историческом центре",
                "type": "branch"
            }
        ],
        "total": 1
    }
}