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:
- Sign in to the Platform Manager.
- 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.
-
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.
List
items.contact_groups
- detailed contact information of the organizationitems.floors
- number of floorsitems.floor_plans
- floor plansitems.links.database_entrances.apartments_info
- information about apartments in the buildingitems.employees_org_count
- number of employees of the organizationitems.itin
- individual tax identification numberitems.trade_license
- trade licenseitems.fias_code
- code of streets or administrative territories in the Federal Information Address Systemitems.address.components.fias_code
- code of buildings in the Federal Information Address Systemitems.fns_code
- Federal Tax Service code of administrative territoriesitems.okato
- code of streets and administrative territories in the National Classifier of Administrative Territorial Entitiesitems.address.components.okato
- code of buildings in the National Classifier of Administrative Territorial Entitiesitems.oktmo
- code of streets and administrative territories in the National Classification of Territories of Municipal Formationsitems.address.components.oktmo
- code of buildings in the National Classification of Territories of Municipal Formationsitems.structure_info.material
- information about the building materialitems.structure_info.apartments_count
- number of apartments in the buildingitems.structure_info.porch_count
- number of entrances in the buildingitems.structure_info.floor_type
- floor type in the buildingitems.structure_info.gas_type
- type of gas supply in the buildingitems.structure_info.year_of_construction
- year of building constructionitems.structure_info.elevators_count
- number of elevators in the buildingitems.structure_info.is_in_emergency_state
- whether the building is considered to be in emergency stateitems.structure_info.project_type
- series or a project of building constructionitems.structure_info.chs_name
- name of the cultural heritage siteitems.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 cafeskey=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
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, thesuggested_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
).