Skip to main content

/3.0/markers/clustered

API docs by Redocly

The directory of object markers (3.0)

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

Markers

Getting a collection of generalized markers

Returns a collection of generalized markers satisfying the parameters passed in the request. A marker is a representation of an object on the map, so only an object with coordinates can be a marker.

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).

fields
Array of strings
Examples:
  • fields=items.name,items.schedule - An example of several fields
  • fields=items.name - An example of a unit field

The additional fields that you want to display in the response, separated by commas.
The list of available fields::

  • items.name — object name;
  • items.org — a company to which the branch belongs;
  • items.context — dynamic information;
  • items.stop_factors — a set of blocking attributes that match the query;
  • items.schedule — opening hours;
  • items.schedule_special — schedule special;
  • items.reviews — statistics on reviews;
  • items.temporary_unavailable_atm_services — indication of the presence of non-functioning services at the ATM or terminal;
  • items.name_back — revealed name in the reverse direction, if available;
  • items.value_back — kilometer number in the reverse direction;
  • items.has_ads_model — an indication of the presence of an advertising 3D model in the building;
  • items.floor_id — floor ID;

map_width
required
integer

The width in pixels for the DOM object that displays the map.

map_height
required
integer

The height in pixels for the DOM object that displays the map.

q
required
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 passing several types, less relevant results of some types may be crowded out by more relevant other types. Types should be 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:

  • branch — company branch;
  • 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 — attraction;
  • crossroad — crossing;
  • gate — passage/thoroughfare;
  • road — road;
  • route — route;
  • adm_div — administrative unit;
  • adm_div.country — country;
  • adm_div.region — region (region/province/republic, etc.);
  • adm_div.city — city;
  • adm_div.district — district;
  • adm_div.district_area — district area;
  • adm_div.division — area;
  • adm_div.living_area — residential community, neighborhood;
  • adm_div.place — various areal objects: parks, beaches, recreation centers, lakes and other places;
  • adm_div.settlement — settlement;
  • adm_div.amana — amana;
  • coordinates — global coordinate in the WGS84 coordinate system in lon, lat format;
  • coordinates_additional — additional global coordinate in the WGS84 coordinate system in lon, lat format;
  • kilometer_road_sign — kilometer road sign.

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

search_type
string
Default: "discovery"

Type of search.
Valid 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_only_within_view
boolean

Specifying the search engine to take results from scope only. The scope (viewport) is set by the parameters viewpoint 1 and `viewpoint2'.

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
search_device_type
string

Device Type:

  • mobile — mobile device
  • desktop — desktop (stationary device)
search_disable_clipping_by_relevance
boolean

Forbid the search to discard results that are not relevant to the query from the output.

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

The ID of the category. You need to pass the option region_id.
you can also pass a list of IDs of categories separated by commas, in this case, all the headings should be from the same region.

org_id
integer

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

ads_id
Array of integers
Examples:
  • ads_id=111,222 - An example of multiple records
  • ads_id=111 - An example of a single record

Advertising campaign ID. You can also pass a list of ads IDs separated by commas.

is_reviewable_on_flamp
boolean

Whether it is allowed to post reviews for companies on flamp.ru. It takes the true or false values.

has_photos
boolean

Filter by availability of photos. Takes the true or false values.

has_rating
boolean

Filter by availability of rating on flamp.ru. Takes the true or false values.

has_reviews
boolean

Filter by availability of reviews on flamp.ru. Takes the true or false values.

has_reviews_on_flamp
boolean

Filter by availability of reviews on flamp.ru. Unlike has_reviews, the link status in 2GIS is not taken into account. It takes the true or false values.

has_site
boolean

Filter by availability of website. Takes the true or false values.

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

Opening hours of the company. 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 which have the opening date later than the passed parameter.
Accepts values in the YYYY-MM-DD format.

has_itin
boolean

Filter by availability of the individual taxpayer identification number. It takes the true or false values.

has_trade_license
boolean

Filter by availability of the trading license. Takes the true or false values.

has_delivery
boolean

Filter by presence of delivery. Takes the values true or false.

has_goods
boolean

Filter by availability of a loaded list of products. Takes the true or false values.

allow_deleted
boolean

To include in the sample remote objects. Can be either true or false.

booking_checkin_date
string <date>
Example: booking_checkin_date=2025-09-02

Filter for selecting available hotel rooms. Checkout date.

booking_checkin_date
string <date>
Example: booking_checkin_date=2025-09-02

Filter for selecting available hotel rooms. Checkout date.

booking_adult_count
integer >= 1
Example: booking_adult_count=2

Filter for selecting available hotel rooms. Number of adults.

booking_children_ages
string
Example: booking_children_ages=7,10

Filter for selecting available hotel rooms. Children's ages separated by commas.

shv
string

Version of the shell. If the parameter has not been passed, the current version of the API will be taken.

sort
string
Default: "relevance"

Sorting of results. Valid values:

  • distance by increasing 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 the 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 (alphabetically ascending).

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

The coordinates of the point from which you are sorting (the coordinates of the point in the lon, lat format). Deprecated parameter, the location parameter should be used instead.

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

User coordinates in the format lon, lat.

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.

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

Place IDs, separated by commas. Used to filter objects in the area.
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

The IDs of the metro stations separated by commas. They are used to filter objects by metro stations.
The maximum number is 50.

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

Polygon in WKT format.
It is used to filter the results in an arbitrary area. The permissible area of the polygon is ~ 6 km^2. If the q parameter is passed, no restrictions are imposed. The parameter conflicts with the parameters point, point1, point2.

viewpoint1
required
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
required
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.

is_viewport_change
boolean

A sign of an obvious change of scope boundaries. Takes the true or false values.

page
integer [ 1 .. 1000000 ]
Default: 1

The number of the requested page.

page_size
integer [ 1 .. 15000 ]
Default: 15000

Number of search results displayed on one page.

header Parameters
Authorization
string

The user authentication header in the session.

Responses

Response Schema: application/json
required
object

Main result

required
object (ObjMeta)

Response metadata

Response samples

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