Overview

The Suggest API is intended for providing suggestions when searching for objects. To display search suggestions, the user 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: for details, see the Suggestion types section.

Additional features

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 a subscription for using API. For details on service prices, see the Tariffs section.
Data on demand
To get certain information about objects, an additional permission is required. Check the list of fields for getting additional information on demand.

For more information on working with access keys and subscriptions, see the account documentation.
Study the request format and response format.
Study the examples of requests to the Suggest API and the full API reference.

If you want to create a search widget on the map, check out the ready-made example of integrating search APIs into a web application.

Additional information on demand

Getting certain information about objects is only available on demand and for an extra cost. Contact the 2GIS 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

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.

Suggestion types

The request parameter suggest_type is responsible for the result of selecting suggestions. By default, suggest_type=object is used, so suggestions relate to the objects from the catalog (categories, companies, streets, cities, etc.).

The most commonly used types of suggestions:

suggestion for catalog objects
address suggestion
suggestions for endpoint of the route

See the full list of suggestion types in the API reference.

Suggestion for catalog objects

The suggestion displays only objects from the catalog: houses, companies, stops, and others. The response contains both text suggestions, which are selected without reference to a map location (for example, "cafe with Wi-Fi"), and particular objects. The results also contain the user's query text complement.

To get suggestions for catalog objects, add the suggest_type=object parameter to the request.

Address suggestion

The suggestion displays possible options based on the entered part of an address.

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

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

Suggestion for endpoints of the route

The suggestion 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 suggestions for a route target point when only a part of the route is specified, add the suggest_type=route_endpoint parameter to the 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
    }
}

The response contains the following parameters:

suggested_text - text of the suggestion.
- For text suggestions, this is the complete query text that the Suggest API suggests based on the text entered by the user.
- For catalog object suggestions, this is one of the object names by which the Suggest API found it. For example, if the user entered "kremlin" and the result is "Moscow Kremlin", then suggested_text will be "Kremlin".
suggest_parts - composite object that shows which part of the text was entered by the user ("is_suggested": false) and which part was added by the API ("is_suggested": true).

Tariffs

The service fee is calculated based on the number of successful requests per month. A successful API request is a request that returns an HTTP code of 200 in the meta.code field of the response. Example:

{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    ...
}

See current prices and rate limits in the Prices section.

Deployment options

Cloud-based: all current Suggest API methods are available through public 2GIS endpoints.
On-Premise: all current Suggest API methods are available when the 2GIS API Platform is installed in a private network. For more information, see the API Platform for server.

Methods labeled as deprecated are not supported in any deployment options.

Support

If you have any questions while working with the API, ask AI assistant (in the lower-right corner of website), use the documentation search, or send an email to api@2gis.com.
If you would like to discuss the capabilities of the API or its integration with your product, please contact a manager.

Getting started​

Additional information on demand​

Request format​

Suggestion types​

Suggestion for catalog objects​

Address suggestion​

Suggestion for endpoints of the route​

Response format​

Tariffs​

Deployment options​

Support​