Overview | 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.

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.

The Suggest API base settings are optimized for faster query input and for its usage together with the Places API. If the query consists of several criteria, for example, "cafe with Wi-Fi", then some of the results will be popular queries or containers.

To get the resulting object from the catalog, pass these queries or containers as input to the Places API. To use the Suggest API without the Places API, specify the appropriate suggest_type as described below.

Here is an example of a request:

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

The request takes the following parameters:

  • q=caf — the search is performed for the "caf" query and allows different suggestions for continuing the query. For example: "cafe", "cafeteria", "caffeine", etc.;
  • location=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. By default, suggest_type=object, so hints relate to the objects from the catalog (categories, companies, streets, cities, etc.).

The most commonly used types of hints are described below. For the complete list of possible suggestion types, see the API reference.

This hint displays only objects from the catalog: houses, companies, stops, and others. The results could contain final objects from the catalog, as well as hints selected without reference to any point on the map, for example, "cafe with Wi-Fi". The results also include text completion for the user's query.

To get an objects hint, add the suggest_type=object parameter to the request.

This hint displays possible options based on the entered part of an address.

To get street names and house numbers in the hint, add the suggest_type=address parameter to the request.

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

This hint displays houses, companies, bus stops, and other catalog items linked to a point on the map. The objects are chosen based on partial or exact matching of the text in the search field.

To get a hint for a route target point when only a part of the route is specified, add the suggest_type=route_endpoint parameter to the request.

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 response contains the following parameters:

  • suggested_text - the hint to be displayed. For text hints, this is the complete text of the hint, which was suggested by the API based on the user's query. For objects from the catalog, this is the description of an object that matched the query. For example, for the "kremlin" query and the "Moscow kremlin" result, the suggested_text will be "Kremlin".

  • suggest_parts - a composite object explaining which portion of the text was entered by the user ("is_suggested": false), and which portion was suggested by the API ("is_suggested": true).

  1. Get your API key:

    1. Sign in to the Platform Manager.
    2. Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.

    In the Platform Manager, you can also:

    • See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
    • Set restrictions for a key by HTTP headers or by IP and subnet.
    • Check the statistics of request distribution for each key.
  2. Learn about the request and response formats.

  3. Check the examples of the Suggest API requests.