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.

Request format

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

Types of hints

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.

• Hint for objects from the catalog
• Address hint
• Hints for endpoints of the route

Hint for objects from the catalog

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.

Address hint

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.

Hints for endpoints of the route

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.

Request response format

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
    }
}

Request response parameters

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

Getting started with the API

1. Get an access key:

   1. Sign in to the Platform Manager.
   2. Create a demo key or purchase an access key for using API: see the Access keys instruction.

   To work with access keys, you can use the Platform Manager: see the Platform Manager section.

2. Learn about the request and response formats.

3. Check the examples of the Suggest API requests.