Suggest API | 2GIS Documentation

Overview

The Suggest API is intended for providing hints when searching for objects. To get tips, the user just needs to start entering text in the search field. The API will suggest possible objects that match the search criteria. The user will only have to choose from the proposed options. The suggestions take into account the location of the user.

suggest

The requests are made using the GET method, and all necessary parameters should be passed in the query string. The responses are generated in JSON format.

Here is an example of a request:

https://catalog.api.2gis.com/3.0/items?q=cafe&sort_point=37.630866,55.752256&key=YOUR_KEY

The request takes the following parameters:

  • q=cafe — search is performed for the “cafe” query
  • sort_point=37.630866,55.752256 — the coordinates of the point next to which a user searches for cafes
  • key=YOUR_KEY — your API key

The request parameter suggest_type is responsible for the result of selecting suggestions. The most commonly used types of hints are described below. For the complete list of possible suggestion types, see the API reference.

The address hint suggests possible options based on the entered part of an address.

To get an address hint, add the suggest_type=address parameter to the request. The hint displays streets and house numbers.

To have only street names in the hint, add suggest_type=street to the request.

To get a hint for an endpoint of the route based on the entered part of it, add the suggest_type=route_endpoint parameter to the request. Houses, companies, bus stops, and other catalog items linked to a point on the map are displayed in the hint. They are chosen based on partial or exact matching the text in the search field.

The hint displays only objects from the catalog: houses, companies, stops, and others. Hints are selected without reference to any point on the map, for example, online stores. The results do not include text completion for the user's query. Add the suggest_type=object parameter to the request to get this kind of hints.

The response to the request is returned in JSON format:

{
    "meta": {
        "api_version": "3.0.428313",
        "code": 200,
        "issue_date": "20200513"
    },
    "result": {
        "items": [
            {
                "search_attributes": {
                    "handling_type": 2,
                    "suggest_parts": [
                        {
                            "is_suggested": false,
                            "text": "caf"
                        },
                        {
                            "is_suggested": true,
                            "text": "e with wifi"
                        }
                    ],
                    "suggested_text": "cafe with wifi"
                },
                "type": "user_query"
            }
        ],
        "total": 1
    }
}

The suggested_text parameter is passed in the response to the request. This can be an assumed text for the user request or a list of objects from the catalog. For the complete list of possible suggestion types, see the API reference.

  1. Fill in the application form to get your key.
  2. Learn about the request and response formats.