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.

Learn about features of other search APIs to enrich your scenarios of working with objects on the map.

Getting started

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

To get certain information about objects, an additional permission is required. Check the list of fields for getting additional information on demand.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.
Learn about the request and response formats.
Check the examples of the Suggest API requests.

Additional information on demand

Getting certain information about objects is only available on demand and for an extra cost. Contact the Urbi sales team to purchase access to the fields below.

The fields are specified in the fields parameter:

items.contact_groups - detailed contact information of the organization
items.floors - number of floors
items.floor_plans - floor plans
items.links.database_entrances.apartments_info - information about apartments in the building
items.employees_org_count - number of employees of the organization
items.itin - individual tax identification number
items.trade_license - trade license
items.fias_code - code of streets or administrative territories in the Federal Information Address System
items.address.components.fias_code - code of buildings in the Federal Information Address System
items.fns_code - Federal Tax Service code of administrative territories
items.okato - code of streets and administrative territories in the National Classifier of Administrative Territorial Entities
items.address.components.okato - code of buildings in the National Classifier of Administrative Territorial Entities
items.oktmo - code of streets and administrative territories in the National Classification of Territories of Municipal Formations
items.address.components.oktmo - code of buildings in the National Classification of Territories of Municipal Formations
items.structure_info.material - information about the building material
items.structure_info.apartments_count - number of apartments in the building
items.structure_info.porch_count - number of entrances in the building
items.structure_info.floor_type - floor type in the building
items.structure_info.gas_type - type of gas supply in the building
items.structure_info.year_of_construction - year of building construction
items.structure_info.elevators_count - number of elevators in the building
items.structure_info.is_in_emergency_state - whether the building is considered to be in emergency state
items.structure_info.project_type - series or a project of building construction
items.structure_info.chs_name - name of the cultural heritage site
items.structure_info.chs_category - category of the cultural heritage site

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