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&location=37.630866,55.752256&key=YOUR_KEY
The request takes the following parameters:
q=cafe
— search is performed for the “cafe” querylocation=37.630866,55.752256
— the coordinates of the point next to which a user searches for cafeskey=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
- Fill in the application form to get your key.
- Learn about the request and response formats.