Skip to main content

Suggests

OpenAPI Specification
API docs by Redocly

Autocomplete (3.0)

2GIS API Support: api@2gis.ru URL: https://docs.2gis.com

Autocomplete

Getting a collection of suggested objects

Returns a collection of objects matching the user input.

The q parameter is required — a search string from 1 to 500 characters.

To control the search area, use one of the following options:

  • location — user coordinates (lon, lat); affects ranking but does not strictly limit results;
  • viewpoint1 + viewpoint2 — rectangular map viewport;
  • region_id — 2GIS region ID.

The suggestion type is set by the suggest_type parameter (default: object). The type of objects to search is specified by the type parameter.

The number of results is controlled by the page_size parameter (from 1 to 100, default 10).

query Parameters
key
required
string

A unique key of API user.

locale
string
Examples:
  • locale=ar_AE - Arabic for the UAE
  • locale=ru_RU - Russian for Russia

The locale with which the search is performed and given results.

List of available locales:

  • ar_AE — Arabic (UAE);
  • ar_BH — Arabic (Bahrain);
  • ar_EG — Arabic (Egypt);
  • ar_IQ — Arabic (Iraq);
  • ar_KW — Arabic (Kuwait);
  • ar_MA — Arabic (Morocco);
  • ar_OM — Arabic (Oman);
  • ar_QA — Arabic (Qatar);
  • ar_RU — Arabic (Russia);
  • ar_SA — Arabic (Saudi Arabia);
  • az_AZ — Azerbaijani (Azerbaijan);
  • cs_CZ — Czech (Czech Republic);
  • cs_RU — Czech (Russia);
  • en_AM — English (Armenia);;
  • en_AE — English (UAE);
  • en_BH — English (Bahrain);
  • en_CN — English (China);
  • en_CY — English (Cyprus);
  • en_EG — English (Egypt);
  • en_IQ — English (Iraq);
  • en_KW — English (Kuwait);
  • en_MA — English (Morocco);
  • en_MN — English (Mongolia);
  • en_OM — English (Oman);
  • en_QA — English (Qatar);
  • en_RU — English (Russia);
  • en_SA — English (Saudi Arabia);
  • es_CL — Spanish (Cyprus);
  • es_RU — Spanish (Russia);
  • hy_AM — Armenian (Armenia);
  • it_IT — Italian (Italy);
  • it_RU — Italian (Russia);
  • ka_GE — Georgian (Georgia);
  • kk_KZ — Kazakh (Kazakhstan);
  • ky_KG — Kyrgyz (Kyrgyzstan);
  • mn_MN — Mongolian (Mongolia);
  • ru_AM — Russian (Armenia);
  • ru_AZ — Russian (Azerbaijan);
  • ru_BY — Russian (Belarus);
  • ru_CN — Russian (China);
  • ru_GE — Russian (Georgia);
  • ru_KG — Russian (Kyrgyzstan);
  • ru_KZ — Russian (Kazakhstan);
  • ru_RU — Russian (Russia);
  • ru_TJ — Russian (Tajikistan);
  • ru_UZ — Russian (Uzbekistan);
  • tg_TJ — Tajik (Tajikistan);
  • uz_UZ — Uzbek (Uzbekistan);
  • zh_CN — Chinese (China).
q
required
string [ 1 .. 500 ] characters

An arbitrary search string.

fields
Array of strings
Examples:
  • fields=items.region_id,items.name_ex - An example of multiple types
  • fields=items.region_id - An example of a single type

Additional fields to be displayed in the response should be separated by commas.

Fields labeled additional permission for the API key is required will be present in the output only if the key has permissions for that field. By default, the key does not have any of the listed additional permissions.

The list of fields containing information on geometry and address of the place:

  • items.point — object coordinates, specified in the WGS84 in the lon, lat format;
  • items.address — address where the object is located;
  • items.adm_div` — belonging to an administrative territory;
  • items.full_address_name — objects address with indication of a city;
  • items.geometry.centroid — visual center of object geometry;
  • items.geometry.hover — geometry of the area used to determine whether the cursor is in the object zone;
  • items.geometry.selection — geometry for object selection.

The list of fields with additional information on the place:

  • items.rubrics — категории компании;
  • items.org — a company to which the branch belongs;
  • items.schedule — opening hours of the company;
  • items.schedule_special — special schedule company;
  • items.access_comment — localized name for the type of access;
  • items.access — access type for a parking lot;
  • items.capacity — parking lot capacity;
  • items.description — map object description;
  • items.flags — a list of object attributes;
  • items.floors — the number of floors (additional permission from the API key is required to obtain the information);
  • items.floor_plans — the plan of floors (additional permission from the API key is required to obtain the information);
  • items.is_paid — whether the parking facility is chargeable or not;
  • items.for_trucks — truck parking;
  • items.paving_type — type of parking paving;
  • items.is_incentive — whether this parking is intercepting;
  • items.purpose — purpose of parking lot;
  • items.level_count — the number of parking facility levels;
  • items.name_ex — components of the object name;
  • items.reviews — statistics on reviews about the object;
  • items.employees_org_count — the number of employees of the organization (additional permission from the API key is required to obtain the information);
  • items.itin — the individual number of the taxpayer (additional permission from the API key is required to obtain the information);
  • items.trade_license — the license of the branch (additional permission from the API key is required to obtain the information);
  • items.fias_code — FIAS code of streets and administrative territories (additional permission from the API key is required to obtain the information);
  • items.address.components.fias_code — FIAS code of buildings (additional permission from the API key is required to obtain the information);
  • items.fns_code — the territory administration code (additional permission from the API key is required to obtain the information);
  • items.okato — OKATO code of streets and administrative territories (additional permission from the API key is required to obtain the information);
  • items.address.components.okato — OKATO code of buildings (additional permission from the API key is required to obtain the information);
  • items.oktmo — OKTMO code of streets and administrative territories (additional permission from the API key is required to obtain the information);
  • items.address.components.oktmo — OKTMO code of buildings (additional permission from the API key is required to obtain the information).

List of service fields:

  • items.context — dynamic information;
  • items.dates.deleted_at — the date when the company data was last deleted in the ISO 8601 format;
  • items.dates.updated_at — the date when the company data was last updated in the ISO 8601 format;
  • items.dates — the time when the information on the company was added to the database;
  • items.geometry.style — style ID for display;
  • items.group — objects gathered in one linked card;
  • items.metarubrics — metarubrics for issuing organizations in a hybrid object;
  • items.is_main_in_group — a sign that it is the main object in the object group of hybrid;
  • items.city_alias — alias of the city, where the object is located;
  • items.delivery — delivery is available;
  • items.is_main_in_group — an attribute meaning that it is the main object in the group of the hybrid objects;
  • items.routes — transport routes passing through the station or public transport stop;
  • items.directions — route directions;
  • items.barrier — type of enclosure;
  • items.is_routing_available — a flag showing whether it is possible to create a route to the object or not;
  • items.is_routing_available — a flag showing whether it is possible to create a route to the object;
  • items.region_id — unique identifier of the project;
  • items.locale — the current locale for the region;
  • items.region_id — unique identifier of the project;
  • items.segment_id — unique identifier of the segment;
  • items.stop_factors — a set of locking attributes corresponding to the query;
  • items.timezone — time zone in POSIX format;
  • items.timezone_offset — the offset the offset at the minute regarding UTC0;
  • items.station_id — the unique identifier of the stop to which this stopping platform is linked;
  • items.platforms — the bus stop platform stop;
  • items.sources — the ID of the object data source;
  • items.structure_info — the data on the number of apartments and the material the building is made of;
  • items.structure_info.material — information about the material the building is made of (additional permission from the API key is required to obtain the information);
  • items.structure_info.apartments_count — data on the number of apartments in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.porch_count — data on the number of entrances (podъezды) in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.floor_type — the type of floors in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.gas_type — type of building gas supply (additional permission from the API key is required to obtain the information);
  • items.structure_info.year_of_construction — year of construction of the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.elevators_count — number of elevators in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.is_in_emergency_state — the fact that the house is recognized as an emergency (additional permission from the API key is required to obtain the information);
  • items.structure_info.project_type — series/project of building construction (additional permission from the API key is required to obtain the information);
  • items.structure_info.chs_name — name of the cultural heritage site (additional permission from the API key is required to obtain the information);
  • items.structure_info.chs_category — category of the object of cultural heritage (additional permission from the API key is required to obtain the information);
  • items.route_logo — metro icon;
  • items.is_deleted — a flag indicating a deleted object;
  • items.search_attributes — parameters of the search result for the found object;
  • items.has_discount — there are discounts;
  • items.poi_category — POI category;
  • items.links — linked objects (nearest parking, public transport stops, and more);
  • items.links.database_entrances — information about entry points (additional permission from the API key is required to obtain the information);
  • items.links.database_entrances.apartments_info — information about the apartments in the building (additional permission from the API key is required to obtain the information);
  • items.purpose_code — building purpose code;
  • items.ads.options — advertising options;
  • search_attributes — information about the performed search;
  • items.name_back — revealed name in the reverse direction, if available;
  • items.value_back — kilometer number in the reverse direction;
  • items.marker_alt — relative marker placement height;
  • items.search_query — a search string that is substituted into the search bar to generate the results (this field is only present for objects of type metarubric);
  • items.tag — unique lowercase name for the category (this field is possible for objects of type metarubric);
  • items.suggest_icon — icon for suggestion results (this field is possible for objects of type rubric);
  • items.has_ads_model — an indication of the presence of an advertising 3D model in the building;
  • items.settlements_group_name — settlement name;
  • items.sport_route_type_name — sport route type;
  • items.seasonal — seasonal attribute of a tourist route;
  • items.source_url — source URL for route information;
  • items.geo_attributes — additional route attributes;
  • items.poi_context_rubrics — list of contex rubrics for POI.
type
Array of strings
Examples:
  • type=branch,building - An example of multiple types
  • type=org - An example of a single type

The types of objects among which the search is performed.

When several types are passed, less relevant results of some types may be displaced by more relevant results of other types. Types are listed comma-separated.

The list of available types:

  • adm_div.district — district;
  • building building;
  • street street;
  • station — public transport stop or station;
  • station.metro — metro station;
  • station_entrance — the entrance to the station;
  • user_queries — user suggestion;
  • adm_div.district is a district;
  • adm_div.district_area is a district of the region;
  • adm_div.settlement — place;
  • adm_div.city is a city;
  • building — building;
  • adm_div.region is the region (oblast/Krai/Republic, etc.);
  • adm_div.place place;
  • adm_div.living_area — zhilmassiv neighborhood;
  • adm_div.division is a district;
  • adm_div.amana — amana;
  • attraction is a tourist attraction;
  • crossroad — intersection;
  • rubric — category;
  • meta_rubric — metacategory;
  • attribute — additional attribute;
  • route — the route;
  • route_type — route type;
  • road — the road;
  • parking — parking lot;
  • org — company;
  • coordinates_additional — additional global coordinate;
  • special — special;
  • special — special;
  • market.category — (deprecated, ignored) product categories;
  • market.suggestor_category — (deprecated, ignored) expanding product categories;
  • market.attribute — (deprecated, ignored) product names;
  • market.brand — (deprecated, ignored) product brand, use brand instead;
  • brand — production brand;
  • kilometer_road_sign — kilometer road sign;
  • road.touristic — tourist routes;
  • friend — friends;
  • directory — geo layer.

The list of available subtypes (subtype) for different object types can be found in the response schema inside items.

suggest_type
string
Default: "object"
Example: suggest_type=route_endpoint

The suggestion matching type being used.

Available types:

  • object — suggestion for directory objects (categories, companies, streets, cities, etc.) — default value;
  • route_endpoint — ideal for quickly searching route endpoint objects. All results have an id and coordinates;
  • address — address suggestion;
  • street — street suggestion;
  • rubric — category suggestion;
  • places — place suggestion;
  • city_selector — locality suggestion. Can be used without specifying a project;
  • cm_endpoint_searcher — route endpoint searcher (Sber integration);
  • cm_endpoint_searcher2 — experimental route endpoint searcher (Sber integration);
  • global_address — deprecated alias for address, use address instead;
  • default — deprecated type, used in version 2.0.
region_id
integer

Region ID.

Required if no geographic search restriction is specified.

Details on how the map is divided into regions can be found in the Regions API description.

location
string
Examples:
  • location=82.921663,55.030195 - Longitude and latitude

User location (coordinate format: lon, lat).

viewpoint1
string
Examples:
  • viewpoint1=82.921663,55.030195 - Longitude and latitude

The coordinates of the top-left vertex of the viewport's rectangular area, in lon, lat format.

The viewpoint1 and viewpoint2 parameters pass the map area the user was viewing before entering the query.

Used as one of the criteria for determining where results are needed, and for ranking. Does not strictly limit the search results to only the specified area.

viewpoint2
string
Examples:
  • viewpoint2=82.921663,55.030195 - Longitude and latitude

The coordinates of the bottom-right vertex of the viewport's rectangular area, in lon, lat format.

The viewpoint1 and viewpoint2 parameters pass the map area the user was viewing before entering the query.

Used as one of the criteria for determining where results are needed, and for ranking. Does not strictly limit the search results to only the specified area.

page_size
integer [ 1 .. 100 ]
Default: 10

Number of search results displayed on one page.

search_is_query_text_complete
boolean

Instructs the search engine that the query is complete (the user pressed the button to finish input).

Disables prefix matching, i.e. searching for "bank" will not find "ATM" ("bankomat").

search_nearby
boolean

Instructs the search engine to use a search mode near the user.

Significantly increases the importance of the distance from the user. Popularity, advertising and other parameters still take part in the ranking, but to a lesser extent.

search_input_method
string

Instructs the search engine on the method of entering the query text:

  • hardware_qwerty_keyboard — physical QWERTY keyboard
  • on_screen_keyboard — on-screen touchscreen keyboard
  • voice — voice input
  • hand_writing — handwritten input
  • scanning — input used by people with disabilities, via finger or eye movements
  • software_generated — the text was generated by software
  • other — other input types
search_territory_of_interest
string
Example: search_territory_of_interest=MULTIPOLYGON (((87.17 53.75, 87.1789 53.75, 87.17 53.755, 87.177 53.75)))

Instructs the search engine to apply a weak restriction on the search area for objects: a penalty for not matching instead of strict exclusion. But there is no advertising outside the TOI.

Requires the WKT format.

Responses

Response Schema: application/json
required
object

Response metadata.

required
object

Main result

Response samples

Content type
application/json
{
  • "meta": {
    • "api_version": "dev",
    • "code": 0,
    • "issue_date": "string"
    },
  • "result": {
    • "items": [
      ],
    • "search_attributes": {
      },
    • "total": 1
    }
}

Getting a collection of suggested objects

Returns a collection of objects matching the user input.

An alternative way to call the /3.0/suggests method by passing parameters in the request body (JSON). Supports all the same parameters as the GET version, plus the polygon parameter for limiting results to an arbitrary polygon.

query Parameters
key
required
string

A unique key of API user.

locale
string
Examples:
  • locale=ar_AE - Arabic for the UAE
  • locale=ru_RU - Russian for Russia

The locale with which the search is performed and given results.

List of available locales:

  • ar_AE — Arabic (UAE);
  • ar_BH — Arabic (Bahrain);
  • ar_EG — Arabic (Egypt);
  • ar_IQ — Arabic (Iraq);
  • ar_KW — Arabic (Kuwait);
  • ar_MA — Arabic (Morocco);
  • ar_OM — Arabic (Oman);
  • ar_QA — Arabic (Qatar);
  • ar_RU — Arabic (Russia);
  • ar_SA — Arabic (Saudi Arabia);
  • az_AZ — Azerbaijani (Azerbaijan);
  • cs_CZ — Czech (Czech Republic);
  • cs_RU — Czech (Russia);
  • en_AM — English (Armenia);;
  • en_AE — English (UAE);
  • en_BH — English (Bahrain);
  • en_CN — English (China);
  • en_CY — English (Cyprus);
  • en_EG — English (Egypt);
  • en_IQ — English (Iraq);
  • en_KW — English (Kuwait);
  • en_MA — English (Morocco);
  • en_MN — English (Mongolia);
  • en_OM — English (Oman);
  • en_QA — English (Qatar);
  • en_RU — English (Russia);
  • en_SA — English (Saudi Arabia);
  • es_CL — Spanish (Cyprus);
  • es_RU — Spanish (Russia);
  • hy_AM — Armenian (Armenia);
  • it_IT — Italian (Italy);
  • it_RU — Italian (Russia);
  • ka_GE — Georgian (Georgia);
  • kk_KZ — Kazakh (Kazakhstan);
  • ky_KG — Kyrgyz (Kyrgyzstan);
  • mn_MN — Mongolian (Mongolia);
  • ru_AM — Russian (Armenia);
  • ru_AZ — Russian (Azerbaijan);
  • ru_BY — Russian (Belarus);
  • ru_CN — Russian (China);
  • ru_GE — Russian (Georgia);
  • ru_KG — Russian (Kyrgyzstan);
  • ru_KZ — Russian (Kazakhstan);
  • ru_RU — Russian (Russia);
  • ru_TJ — Russian (Tajikistan);
  • ru_UZ — Russian (Uzbekistan);
  • tg_TJ — Tajik (Tajikistan);
  • uz_UZ — Uzbek (Uzbekistan);
  • zh_CN — Chinese (China).
q
required
string [ 1 .. 500 ] characters

An arbitrary search string.

fields
Array of strings
Examples:
  • fields=items.region_id,items.name_ex - An example of multiple types
  • fields=items.region_id - An example of a single type

Additional fields to be displayed in the response should be separated by commas.

Fields labeled additional permission for the API key is required will be present in the output only if the key has permissions for that field. By default, the key does not have any of the listed additional permissions.

The list of fields containing information on geometry and address of the place:

  • items.point — object coordinates, specified in the WGS84 in the lon, lat format;
  • items.address — address where the object is located;
  • items.adm_div` — belonging to an administrative territory;
  • items.full_address_name — objects address with indication of a city;
  • items.geometry.centroid — visual center of object geometry;
  • items.geometry.hover — geometry of the area used to determine whether the cursor is in the object zone;
  • items.geometry.selection — geometry for object selection.

The list of fields with additional information on the place:

  • items.rubrics — категории компании;
  • items.org — a company to which the branch belongs;
  • items.schedule — opening hours of the company;
  • items.schedule_special — special schedule company;
  • items.access_comment — localized name for the type of access;
  • items.access — access type for a parking lot;
  • items.capacity — parking lot capacity;
  • items.description — map object description;
  • items.flags — a list of object attributes;
  • items.floors — the number of floors (additional permission from the API key is required to obtain the information);
  • items.floor_plans — the plan of floors (additional permission from the API key is required to obtain the information);
  • items.is_paid — whether the parking facility is chargeable or not;
  • items.for_trucks — truck parking;
  • items.paving_type — type of parking paving;
  • items.is_incentive — whether this parking is intercepting;
  • items.purpose — purpose of parking lot;
  • items.level_count — the number of parking facility levels;
  • items.name_ex — components of the object name;
  • items.reviews — statistics on reviews about the object;
  • items.employees_org_count — the number of employees of the organization (additional permission from the API key is required to obtain the information);
  • items.itin — the individual number of the taxpayer (additional permission from the API key is required to obtain the information);
  • items.trade_license — the license of the branch (additional permission from the API key is required to obtain the information);
  • items.fias_code — FIAS code of streets and administrative territories (additional permission from the API key is required to obtain the information);
  • items.address.components.fias_code — FIAS code of buildings (additional permission from the API key is required to obtain the information);
  • items.fns_code — the territory administration code (additional permission from the API key is required to obtain the information);
  • items.okato — OKATO code of streets and administrative territories (additional permission from the API key is required to obtain the information);
  • items.address.components.okato — OKATO code of buildings (additional permission from the API key is required to obtain the information);
  • items.oktmo — OKTMO code of streets and administrative territories (additional permission from the API key is required to obtain the information);
  • items.address.components.oktmo — OKTMO code of buildings (additional permission from the API key is required to obtain the information).

List of service fields:

  • items.context — dynamic information;
  • items.dates.deleted_at — the date when the company data was last deleted in the ISO 8601 format;
  • items.dates.updated_at — the date when the company data was last updated in the ISO 8601 format;
  • items.dates — the time when the information on the company was added to the database;
  • items.geometry.style — style ID for display;
  • items.group — objects gathered in one linked card;
  • items.metarubrics — metarubrics for issuing organizations in a hybrid object;
  • items.is_main_in_group — a sign that it is the main object in the object group of hybrid;
  • items.city_alias — alias of the city, where the object is located;
  • items.delivery — delivery is available;
  • items.is_main_in_group — an attribute meaning that it is the main object in the group of the hybrid objects;
  • items.routes — transport routes passing through the station or public transport stop;
  • items.directions — route directions;
  • items.barrier — type of enclosure;
  • items.is_routing_available — a flag showing whether it is possible to create a route to the object or not;
  • items.is_routing_available — a flag showing whether it is possible to create a route to the object;
  • items.region_id — unique identifier of the project;
  • items.locale — the current locale for the region;
  • items.region_id — unique identifier of the project;
  • items.segment_id — unique identifier of the segment;
  • items.stop_factors — a set of locking attributes corresponding to the query;
  • items.timezone — time zone in POSIX format;
  • items.timezone_offset — the offset the offset at the minute regarding UTC0;
  • items.station_id — the unique identifier of the stop to which this stopping platform is linked;
  • items.platforms — the bus stop platform stop;
  • items.sources — the ID of the object data source;
  • items.structure_info — the data on the number of apartments and the material the building is made of;
  • items.structure_info.material — information about the material the building is made of (additional permission from the API key is required to obtain the information);
  • items.structure_info.apartments_count — data on the number of apartments in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.porch_count — data on the number of entrances (podъezды) in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.floor_type — the type of floors in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.gas_type — type of building gas supply (additional permission from the API key is required to obtain the information);
  • items.structure_info.year_of_construction — year of construction of the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.elevators_count — number of elevators in the building (additional permission from the API key is required to obtain the information);
  • items.structure_info.is_in_emergency_state — the fact that the house is recognized as an emergency (additional permission from the API key is required to obtain the information);
  • items.structure_info.project_type — series/project of building construction (additional permission from the API key is required to obtain the information);
  • items.structure_info.chs_name — name of the cultural heritage site (additional permission from the API key is required to obtain the information);
  • items.structure_info.chs_category — category of the object of cultural heritage (additional permission from the API key is required to obtain the information);
  • items.route_logo — metro icon;
  • items.is_deleted — a flag indicating a deleted object;
  • items.search_attributes — parameters of the search result for the found object;
  • items.has_discount — there are discounts;
  • items.poi_category — POI category;
  • items.links — linked objects (nearest parking, public transport stops, and more);
  • items.links.database_entrances — information about entry points (additional permission from the API key is required to obtain the information);
  • items.links.database_entrances.apartments_info — information about the apartments in the building (additional permission from the API key is required to obtain the information);
  • items.purpose_code — building purpose code;
  • items.ads.options — advertising options;
  • search_attributes — information about the performed search;
  • items.name_back — revealed name in the reverse direction, if available;
  • items.value_back — kilometer number in the reverse direction;
  • items.marker_alt — relative marker placement height;
  • items.search_query — a search string that is substituted into the search bar to generate the results (this field is only present for objects of type metarubric);
  • items.tag — unique lowercase name for the category (this field is possible for objects of type metarubric);
  • items.suggest_icon — icon for suggestion results (this field is possible for objects of type rubric);
  • items.has_ads_model — an indication of the presence of an advertising 3D model in the building;
  • items.settlements_group_name — settlement name;
  • items.sport_route_type_name — sport route type;
  • items.seasonal — seasonal attribute of a tourist route;
  • items.source_url — source URL for route information;
  • items.geo_attributes — additional route attributes;
  • items.poi_context_rubrics — list of contex rubrics for POI.
type
Array of strings
Examples:
  • type=branch,building - An example of multiple types
  • type=org - An example of a single type

The types of objects among which the search is performed.

When several types are passed, less relevant results of some types may be displaced by more relevant results of other types. Types are listed comma-separated.

The list of available types:

  • adm_div.district — district;
  • building building;
  • street street;
  • station — public transport stop or station;
  • station.metro — metro station;
  • station_entrance — the entrance to the station;
  • user_queries — user suggestion;
  • adm_div.district is a district;
  • adm_div.district_area is a district of the region;
  • adm_div.settlement — place;
  • adm_div.city is a city;
  • building — building;
  • adm_div.region is the region (oblast/Krai/Republic, etc.);
  • adm_div.place place;
  • adm_div.living_area — zhilmassiv neighborhood;
  • adm_div.division is a district;
  • adm_div.amana — amana;
  • attraction is a tourist attraction;
  • crossroad — intersection;
  • rubric — category;
  • meta_rubric — metacategory;
  • attribute — additional attribute;
  • route — the route;
  • route_type — route type;
  • road — the road;
  • parking — parking lot;
  • org — company;
  • coordinates_additional — additional global coordinate;
  • special — special;
  • special — special;
  • market.category — (deprecated, ignored) product categories;
  • market.suggestor_category — (deprecated, ignored) expanding product categories;
  • market.attribute — (deprecated, ignored) product names;
  • market.brand — (deprecated, ignored) product brand, use brand instead;
  • brand — production brand;
  • kilometer_road_sign — kilometer road sign;
  • road.touristic — tourist routes;
  • friend — friends;
  • directory — geo layer.

The list of available subtypes (subtype) for different object types can be found in the response schema inside items.

suggest_type
string
Default: "object"
Example: suggest_type=route_endpoint

The suggestion matching type being used.

Available types:

  • object — suggestion for directory objects (categories, companies, streets, cities, etc.) — default value;
  • route_endpoint — ideal for quickly searching route endpoint objects. All results have an id and coordinates;
  • address — address suggestion;
  • street — street suggestion;
  • rubric — category suggestion;
  • places — place suggestion;
  • city_selector — locality suggestion. Can be used without specifying a project;
  • cm_endpoint_searcher — route endpoint searcher (Sber integration);
  • cm_endpoint_searcher2 — experimental route endpoint searcher (Sber integration);
  • global_address — deprecated alias for address, use address instead;
  • default — deprecated type, used in version 2.0.
region_id
integer

Region ID.

Required if no geographic search restriction is specified.

Details on how the map is divided into regions can be found in the Regions API description.

location
string
Examples:
  • location=82.921663,55.030195 - Longitude and latitude

User location (coordinate format: lon, lat).

viewpoint1
string
Examples:
  • viewpoint1=82.921663,55.030195 - Longitude and latitude

The coordinates of the top-left vertex of the viewport's rectangular area, in lon, lat format.

The viewpoint1 and viewpoint2 parameters pass the map area the user was viewing before entering the query.

Used as one of the criteria for determining where results are needed, and for ranking. Does not strictly limit the search results to only the specified area.

viewpoint2
string
Examples:
  • viewpoint2=82.921663,55.030195 - Longitude and latitude

The coordinates of the bottom-right vertex of the viewport's rectangular area, in lon, lat format.

The viewpoint1 and viewpoint2 parameters pass the map area the user was viewing before entering the query.

Used as one of the criteria for determining where results are needed, and for ranking. Does not strictly limit the search results to only the specified area.

polygon
string
Examples:
  • polygon=POLYGON((82.91259527206421 55.0614369017519,82.90572881698608 55.05902823221974,82.91521310806274 55.05580825372468,82.91259527206421 55.0614369017519)) - WKT format

A polygon in WKT format.

Used for filtering results within an arbitrary area. The allowed polygon area is ~6 km². If the q parameter is passed, no restrictions are applied.

The parameter conflicts with the point, point1, point2 parameters.

page_size
integer [ 1 .. 100 ]
Default: 10

Number of search results displayed on one page.

Request Body schema: application/json

Request in json format.

Array of objects

Records personal to the user with information about weight, etc.

object

Query context.

Responses

Response Schema: application/json
required
object

Response metadata.

required
object

Main result

Request samples

Content type
application/json
{
  • "personal_records": [
    • {
      }
    ],
  • "query_context": {
    • "best_keyword": "string",
    • "viewport_action": {
      }
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    • "api_version": "dev",
    • "code": 0,
    • "issue_date": "string"
    },
  • "result": {
    • "items": [
      ],
    • "search_attributes": {
      },
    • "total": 1
    }
}