Skip to main content

Search for places

OpenAPI Specification
API docs by Redocly

Catalog of objects (3.0)

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

The difference between version 2.0 and 3.0 is that in 3.0 you can obtain all types of data — companies, map objects, routes and stops — in response to a single request, while in 2.0 you have to make several requests to obtain the same.

Catalog

Getting a collection of objects

Searches for locations based on the specified query and shows a paginated list of results.

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
string [ 1 .. 500 ] characters

An arbitrary search string.

type
Array of strings
Examples:
  • type=adm_div,street - An example of multiple types
  • type=adm_div - 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 adm_div value is an alias for all adm_div.* types at one and the same time.

The list of available types:

  • adm_div.district — district;
  • building building;
  • street street;
  • parking — parking lot;
  • station — public transport stop or station;
  • station.metro — metro station;
  • station_entrance — the entrance to the station;
  • station_platform — stopping platform;
  • attraction is a tourist attraction;
  • crossroad — intersection;
  • gate — passage/thoroughfare;
  • road — the road;
  • route — the route;
  • adm_div — administrative unit;
  • adm_div.city is a city;
  • building — building;
  • adm_div.district_area is a district of the region;
  • adm_div.district is a district;
  • adm_div.division is a district;
  • adm_div.living_area — zhilmassiv neighborhood;
  • adm_div.place place;
  • adm_div.region is the region (oblast/Krai/Republic, etc.);
  • adm_div.settlement — place;
  • adm_div.amana — amana;
  • coordinates_additional — additional global coordinate;
  • special — special;
  • kilometer_road_sign — kilometer road sign.

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

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 — категории компании;
  • items.org — a company to which the branch belongs;
  • items.brand — brand to which the branch belongs;
  • items.contact_groups — the company's contact details (additional permission from the API key is required to obtain the information);
  • 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.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.name_ex — components of the object name;
  • items.reviews — statistics on reviews about the object;
  • items.statistics — summary of geo;
  • 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:

  • context_rubrics — an array of contextual headings;
  • dym — the block «you Probably mean»;
  • filters — filters for additional search;
  • hash — underlying hash;
  • items.ads.options — advertising options;
  • items.attribute_groups — additional attributes of the company;
  • 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.delivery — delivery is available;
  • items.has_goods — the list of the company's products was uploaded;
  • items.has_pinned_goods — the company has turned on the «Pinned goods» section;
  • items.has_realty — there is property on sale;
  • items.has_audiogid — whether the item has an audio guide;
  • items.has_discount — there are discounts;
  • items.has_exchange — indicates whether the branch has currency exchange rates;
  • 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.is_promoted — the company participates in a special offer from the Check;
  • 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.reg_bc_url — enrollment URL of the business konnekshn view profile;
  • items.region_id — unique identifier of the project;
  • items.segment_id — unique identifier of the segment;
  • items.stat — data to generate message statistics;
  • items.stop_factors — a set of locking attributes corresponding to the query;
  • items.has_apartments_info — flag indicating the presence of information about apartments in the building;
  • 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, requires additional permission from the API key;
  • 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.order_with_cart — order properties for a company without delivery, but with a cart;
  • items.is_deleted — a sign of 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.has_dynamic_congestion — flag indicating the presence of an online value for the branch's current congestion;
  • items.temporary_unavailable_atm_services — indication of the presence of non-functioning services at the ATM or terminal;
  • items.marker_alt — relative marker placement height;
  • items.floor_id — floor ID;
  • items.purpose_code — building purpose code;
  • request_type — type the search request;
  • search_attributes — information about the performed search;
  • widgets — widgets;
  • items.name_back — revealed name in the reverse direction, if available;
  • items.value_back — kilometer number in the reverse direction;
  • items.ev_charging_station — attributes of EV charging stations;
  • items.ski_lift — information about a ski lift;
  • items.has_ads_model — an indication of the presence of an advertising 3D model in the building;
  • items.has_otello_stories — flag indicating the presence of stories from Otello for the branch;
  • items.has_otello_hotels — flag indicating the presence of hotels in Otello;
  • items.summary — block of summarized information;
  • items.settlements_group_name — settlement name;
  • items.sport_route_type_name — sport route type;
  • items.booking — block with an offer from the hotel;
  • items.ski_track — information about a ski track;
  • 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.
search_type
string
Default: "discovery"

The type of search being performed.

Allowed values:

  • discovery — the widest possible search with the possibility to open the linked objects (categories, corresponding to the request, will be opened before the branches that belong to them);
  • one_branch — identical to discovery, but only one branch will be shown for a company;
  • indoor — the configuration for high-quality search for branches in the building;
  • ads — identical to discovery, but it will display only objects with advertising. In addition, only one branch, which if the first in the ranking, will be shown for a company;
  • discovery_partial_searcher — identical to discovery, but it involves more options of intersection of links;
  • discovery_partial_searcher_strict — identical to discovery_partial_searcher, but the prefix search will be disabled.
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.

sort
string
Default: "relevance"

Sorting of the results.

Allowed values:

  • distance — in ascending order of distance, if the sort_point, point or location parameter is passed (the distance is calculated from the passed point to the object geometry along the shortest path), otherwise — sorting by object type and its area;
  • relevance — by descending order of the relevance. The search involves the company name and categories, to which the company belongs. It takes into account a maximum of different factors: the accuracy of matching the request to the object, the popularity of objects, rating, location, advertising and much more;
  • rating — by descending order of the rating;
  • flamp_rating — by descending rating on Flamp;
  • creation_time — by descending order of the date of the establishment of the company branch;
  • opened_time — by descending order of the opening date;
  • name — by name (in alphabetical ascending order).
sort_point
string
Deprecated
Examples:
  • sort_point=82.921663,55.030195 - Longitude and latitude

The coordinates of the point from which sorting is performed (point coordinates in lon, lat format). A deprecated parameter; the location parameter should be used instead.

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

User location (coordinate format: lon, lat).

lon
number <double> ( -180 .. 180 )
Examples:
  • lon=82.921663 - Longitude

The longitude of the point — the center of the search area.

The allowed range of values: from -180 to 180.

Must be used together with the lat parameter. Can be used together with the radius parameter to filter results within a circle.

lat
number <double> ( -90 .. 90 )
Examples:
  • lat=55.030195 - Latitude

The latitude of the point — the center of the search area.

The allowed range of values: from -90 to 90.

Must be used together with the lon parameter. Can be used together with the radius parameter to filter results within a circle.

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

The center of the search area (point coordinates in lon, lat format).

Used for filtering results within a circle.

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

radius
integer [ 0 .. 50000 ]
Default: 250

The search radius in meters.

Limit: from 0 to 50000 when a search query (q, org_id, rubric_id, ip, etc.) is present, from 0 to 2000 when it is absent. Default value: 250 when used together with point, 0 when used together with lon/lat.

Used for filtering results within a circle.

district_id
Array of integers
Examples:
  • district_id=141347373711435,141347373711473,141347373711478 - An example of multiple IDs
  • district_id=141347373711435 - An example of a single ID

The IDs of the districts, separated by commas. They are used to filter objects by district.

The maximum number is 50.

Can only be used in conjunction with the type=branch parameter.

building_id
Array of integers
Examples:
  • building_id=141373143515660,141373143523268 - An example of multiple IDs
  • building_id=141373143515660 - An example of a single ID

The IDs of the buildings, separated by commas. They are used to filter objects in a building.

The maximum number is 50.

place_id
Array of integers
Examples:
  • place_id=141424683123045,141424683123024 - An example of multiple IDs
  • place_id=141424683123045 - An example of a single ID

Comma-separated place identifiers. Used for filtering objects within a territory.

The maximum number is 50.

city_id
Array of integers
Examples:
  • city_id=141373143515660,141373143523268 - An example of multiple IDs
  • city_id=141373143515660 - An example of a single ID

The IDs of the cities separated by commas. They are used to filter objects by cities.

The maximum number is 50.

subway
Array of integers
Examples:
  • subway=141523467371731,141523467371220 - An example of multiple IDs
  • subway=141523467371731 - An example of a single ID

Comma-separated metro station identifiers. Used for filtering objects by metro stations.

The maximum number is 50.

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

The coordinates of the top-left vertex of the rectangular area, in lon, lat format, that limits the results of the selection.

Used for filtering results within a rectangular area. The maximum distance between the point1 and point2 points is no more than 2 km.

If the q parameter is passed, no restrictions are applied.

The parameter conflicts with the point, polygon parameters.

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

The coordinates of the bottom-right vertex of the rectangular area, in lon, lat format, that limits the results of the selection.

Used for filtering results within a rectangular area. The maximum distance between the point2 and point1 points is no more than 2 km.

If the q parameter is passed, no restrictions are applied.

The parameter conflicts with the point, polygon parameters.

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.

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.

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.

page
integer [ 1 .. 1000000 ]
Default: 1

The number of the requested page.

page_size
integer [ 1 .. 50 ]
Default: 20

Number of search results displayed on one page.

rubric_id
Array of integers
Examples:
  • rubric_id=19290,360 - An example of multiple records
  • rubric_id=19290 - An example of a single record

Category ID.

The region_id parameter must be passed.

A comma-separated list of category identifiers can also be passed. In this case, all categories must belong to the same region.

org_id
integer

Filter by the ID of the organization to which the company belongs.

brand_id
integer

Filter by the brand ID to which the company belongs.

has_photos
boolean

Filter by the presence of photos. Can be either true or false.

has_rating
boolean

Filter by the presence of a rating on flamp.ru. Can be either true or false.

has_reviews
boolean

Filter by the presence of reviews on flamp.ru. Can be either true or false.

has_site
boolean

Filter by the presence of a website. Can be either true or false.

work_time
string
Examples:
  • work_time=now - Right now
  • work_time=tue,alltime - On Tuesday, open 24 hours

The company's working hours. Format: [day],[time] or now (current day and time).

Examples:

  • Monday, 17:00 — mon,17:00
  • Thursday, 9:00 — thu,09:00
  • Today, 9:00 — today,09:00
  • Friday, all day — fri,alltime
  • Now now
opened_after_date
string <date>
Examples:
  • opened_after_date=2007-09-03 - Later than September 3, 2007

Filters companies whose opening date is later than the passed parameter. Accepts values in the YYYY-MM-DD format.

has_itin
boolean

Filter by the presence of an individual taxpayer number. Can be either true or false.

has_trade_license
boolean

Filter by the presence of a trade license.

Accepts the values true or false.

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": {
    • "ad": {
      },
    • "context_rubrics": [
      ],
    • "items": [
      ],
    • "search_attributes": {
      },
    • "total": 1
    }
}