Skip to main content

Suggests

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 that match the user input.

query Parameters
key
required
string

Unique key of API user.

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

The locale from which the search is performed and the results are given.
List of available locales:

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

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 these 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 — categories of the company;
  • 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_name — localized name of 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_plan — 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.links — linked objects (nearest parking, public transport stops, and more);
  • items.links.database_entrances — information about entry points (requires additional permission on the API key);
  • 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.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;
  • items.address.components.fias_code — FIAS code of buildings;
  • items.fns_code — FNS code of administrative territories (additional permission for API key is required);
  • items.okato — OKATO code of streets and administrative territories (additional permission for API key is required);
  • items.address.components.okato — OKATO code of buildings (additional permission for API key is required);
  • items.oktmo — OKTMO code of streets and administrative territories (additional permission for API key is required);
  • items.address.components.oktmo — OKTMO code of buildings (additional permission for API key is required);

The list of command boxes:
  • 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.detailed_subtype — detailed type of administrative-territorial unit;
  • items.group — objects gathered in one linked card;
  • 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.floor_id — floor ID;
  • items.is_routing_available — a flag showing whether it is possible to create a route to the object or not;
  • items.locale — 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 blocking attributes that match the query;
  • items.has_apartments_info — an attribute of availability of information on apartments in the building;
  • items.timezone — timezone in the POSIX format;
  • items.timezone_offset — the offset the offset at the minute regarding UTC0;
  • items.comment — comment for the entrance;
  • 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 (additional permission from the API key is required to obtain the information;
  • 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 — the data on the number of apartments (additional permission from the API key is required to obtain the information;
  • items.structure_info.porch_count — the data on the number of entrances (additional permission from the API key is required to obtain the information;
  • items.route_logo — icon of the underground;
  • items.is_deleted — a sign of a deleted object;
  • items.search_attributes — parameters of the search result for the found object. Each field inside items.search_attributes must be queried separately through a dot, for example, items.search_attributes.segment_id. The list of available fields inside the items.search_attributes object can be viewed in the response schema for any object inside items;
  • items.congestion — branch congestion;
  • items.marker_alt — relative height of marker placement;
  • items.purpose_code — code of the purpose of the building;
  • items.poi_category — POI category;
  • search_attributes — information about the performed search;
  • items.name_back — for the road sign, the localized name in the reverse direction, if available;
  • items.value_back — for the road sign, the number of the kilometer in the reverse direction;
  • items.ev_charging_station — attributes for charging stations.;
  • items.has_ads_model — an indication of the presence of an advertising 3D model in the building;

type
Array of strings
Examples:
  • type=org,discount - An example of multiple types
  • type=org - An example of a single type

The types of objects among which the search is performed. When passing several types, less relevant results of some types may be crowded out by more relevant other types. The types should be comma separated.
The list of available types:

  • adm_div.district — district;
  • adm_div.district_area — district area;
  • adm_div.settlement — settlement;
  • adm_div.city — city;
  • adm_div.country — country;
  • adm_div.region — region (region/province/republic, etc.);
  • adm_div.place — place;
  • adm_div.living_area — neighborhood, residential community;
  • adm_div.division — area;
  • adm_div.amana — amana;
  • building — building;
  • station — stop;
  • street — street;
  • attraction — attraction;
  • crossroad — intersection;
  • station.metro — metro station;
  • station_entrance;
  • branch — company branch office;
  • rubric — category;
  • meta_rubric — metacategory;
  • attribute — additional attribute;
  • route — route;
  • route_type — route type;
  • road — road;
  • parking — parking lot;
  • org — company;
  • coordinates — global coordinate;
  • coordinates_additional — additional global coordinate;
  • special — special;
  • market.category — product categories. Requires market.suggestor_category;
  • market.suggestor_category — required to open product categories;
  • market.attribute — product names;
  • market.brand — products brand;
  • kilometer_road_sign — kilometer road sign;
  • road.touristic — tourist routes.

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

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

The type of tips to use. Available types:

  • route_endpoint — perfect for a quick search of final objects of the route. All the results have id and coordinates;
  • rubric — category tips;
  • places - place tips;
  • address - address tips;
  • global_address — alias of address. Deprecated type, you need to use address instead;
  • city_selector — settlement suggests. Can be used without specifying a project;
  • object — tips on directory objects (categories, companies, streets, cities, etc.);
  • default - used by default (object).

region_id
integer

Region identifier. It is required if a geographical limit of search has not been specified. Details about the territorial division of the map into regions can be found in the description of the Regions API.

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 upper left vertex of a rectangular visibility scope, in the lon, lat format. The parameters viewpoint 1 and viewpoint 2 transmit the area of the map where the user looked before entering the request. It is used as one of the criteria for choosing where results are needed and for ranking. Does not strictly restrict the search results to the transmitted area only.

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

The coordinates of the lower right vertex of a rectangular visibility scope, in the lon, lat format. The viewpoint1 and viewpoint2 parameters pass the map area where the user looked before entering the request. It is used as one of the criteria for choosing where results are needed and for ranking. Does not strictly restrict the search results to the transmitted area only.

page_size
integer [ 1 .. 100 ]
Default: 10

Number of search results displayed on one page.

search_is_query_text_complete
boolean

Specifying to the search engine that the request is complete (the user has pressed the completion button). Disables the prefix, i.e. "bank" will not be searched "banking".

search_nearby
boolean

Specifying the search engine to use search mode near the user. Greatly increases the importance of distance from the user. Popularity, advertising and other parameters are still involved in the ranking, but to a lesser extent.

search_input_method
string

Specifying the method for entering the query text to the search engine:

  • hardware_qwerty_keyboard — physical QWERTY keyboard
  • on_screen_keyboard — touch screen keyboard
  • voice — voice input
  • hand_writing — handwriting input
  • scanning — input that is used by people with disabilities. Using your finger or eye movements
  • software_generated — software-generated text
  • ʻother` — other input types

Responses

Response Schema: application/json
required
object

Main result

required
object (ObjMeta)

Response metadata

Response samples

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

Getting a collection of suggested objects

Returns a collection of objects that match the user input.

query Parameters
key
required
string

Unique key of API user.

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

The locale from which the search is performed and the results are given.
List of available locales:

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

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 these 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 — categories of the company;
  • 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_name — localized name of 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_plan — 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.links — linked objects (nearest parking, public transport stops, and more);
  • items.links.database_entrances — information about entry points (requires additional permission on the API key);
  • 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.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;
  • items.address.components.fias_code — FIAS code of buildings;
  • items.fns_code — FNS code of administrative territories (additional permission for API key is required);
  • items.okato — OKATO code of streets and administrative territories (additional permission for API key is required);
  • items.address.components.okato — OKATO code of buildings (additional permission for API key is required);
  • items.oktmo — OKTMO code of streets and administrative territories (additional permission for API key is required);
  • items.address.components.oktmo — OKTMO code of buildings (additional permission for API key is required);

The list of command boxes:
  • 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.detailed_subtype — detailed type of administrative-territorial unit;
  • items.group — objects gathered in one linked card;
  • 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.floor_id — floor ID;
  • items.is_routing_available — a flag showing whether it is possible to create a route to the object or not;
  • items.locale — 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 blocking attributes that match the query;
  • items.has_apartments_info — an attribute of availability of information on apartments in the building;
  • items.timezone — timezone in the POSIX format;
  • items.timezone_offset — the offset the offset at the minute regarding UTC0;
  • items.comment — comment for the entrance;
  • 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 (additional permission from the API key is required to obtain the information;
  • 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 — the data on the number of apartments (additional permission from the API key is required to obtain the information;
  • items.structure_info.porch_count — the data on the number of entrances (additional permission from the API key is required to obtain the information;
  • items.route_logo — icon of the underground;
  • items.is_deleted — a sign of a deleted object;
  • items.search_attributes — parameters of the search result for the found object. Each field inside items.search_attributes must be queried separately through a dot, for example, items.search_attributes.segment_id. The list of available fields inside the items.search_attributes object can be viewed in the response schema for any object inside items;
  • items.congestion — branch congestion;
  • items.marker_alt — relative height of marker placement;
  • items.purpose_code — code of the purpose of the building;
  • items.poi_category — POI category;
  • search_attributes — information about the performed search;
  • items.name_back — for the road sign, the localized name in the reverse direction, if available;
  • items.value_back — for the road sign, the number of the kilometer in the reverse direction;
  • items.ev_charging_station — attributes for charging stations.;
  • items.has_ads_model — an indication of the presence of an advertising 3D model in the building;

type
Array of strings
Examples:
  • type=org,discount - An example of multiple types
  • type=org - An example of a single type

The types of objects among which the search is performed. When passing several types, less relevant results of some types may be crowded out by more relevant other types. The types should be comma separated.
The list of available types:

  • adm_div.district — district;
  • adm_div.district_area — district area;
  • adm_div.settlement — settlement;
  • adm_div.city — city;
  • adm_div.country — country;
  • adm_div.region — region (region/province/republic, etc.);
  • adm_div.place — place;
  • adm_div.living_area — neighborhood, residential community;
  • adm_div.division — area;
  • adm_div.amana — amana;
  • building — building;
  • station — stop;
  • street — street;
  • attraction — attraction;
  • crossroad — intersection;
  • station.metro — metro station;
  • station_entrance;
  • branch — company branch office;
  • rubric — category;
  • meta_rubric — metacategory;
  • attribute — additional attribute;
  • route — route;
  • route_type — route type;
  • road — road;
  • parking — parking lot;
  • org — company;
  • coordinates — global coordinate;
  • coordinates_additional — additional global coordinate;
  • special — special;
  • market.category — product categories. Requires market.suggestor_category;
  • market.suggestor_category — required to open product categories;
  • market.attribute — product names;
  • market.brand — products brand;
  • kilometer_road_sign — kilometer road sign;
  • road.touristic — tourist routes.

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

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

The type of tips to use. Available types:

  • route_endpoint — perfect for a quick search of final objects of the route. All the results have id and coordinates;
  • rubric — category tips;
  • places - place tips;
  • address - address tips;
  • global_address — alias of address. Deprecated type, you need to use address instead;
  • city_selector — settlement suggests. Can be used without specifying a project;
  • object — tips on directory objects (categories, companies, streets, cities, etc.);
  • default - used by default (object).

region_id
integer

Region identifier. It is required if a geographical limit of search has not been specified. Details about the territorial division of the map into regions can be found in the description of the Regions API.

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 upper left vertex of a rectangular visibility scope, in the lon, lat format. The parameters viewpoint 1 and viewpoint 2 transmit the area of the map where the user looked before entering the request. It is used as one of the criteria for choosing where results are needed and for ranking. Does not strictly restrict the search results to the transmitted area only.

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

The coordinates of the lower right vertex of a rectangular visibility scope, in the lon, lat format. The viewpoint1 and viewpoint2 parameters pass the map area where the user looked before entering the request. It is used as one of the criteria for choosing where results are needed and for ranking. Does not strictly restrict the search results to the transmitted area only.

page_size
integer [ 1 .. 100 ]
Default: 10

Number of search results displayed on one page.

Request Body schema: application/json

Query in json format.

Array of objects

Personal records for the user with information about weight, etc.

Array
type
string
Enum: "home" "work" "favorites" "history" "personal_poi" "supposed_home" "supposed_work" "supposed_other"

The personal type of the object.

count
integer

The number of accesses to the object during the period.

last_used
number <int64>

The last time Unix timestamp was used, in seconds.

probability
number [ 0 .. 1 ]

The probability that the source object is personal.

object

Full record identification = type + ID.

object

The point of result coordinates. If the object doesn't have its own point - the center of a segment where the object is located will be given.

Responses

Response Schema: application/json
required
object

Main result

required
object (ObjMeta)

Response metadata

Request samples

Content type
application/json
{
  • "personal_records": [
    • {
      }
    ]
}

Response samples

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