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.

Request 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

Types of hints

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.

Address hint

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.

Hints for endpoints of the route

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.

Hint for objects from the catalog

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.

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

Getting started with the API

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