Сервис определяет геообъект, «доминирующий» в текущем viewport пользователя — то есть наиболее крупный и значимый объект, который покрывает или соответствует видимой области карты. Используется для отображения контекстного заголовка карты (например, «Москва», «Пресненский район»).
| Параметр | Тип | Обяз. | По умолчанию | Описание | Пример |
|---|---|---|---|---|---|
bbox |
string | да | — | Границы viewport в формате min_lon,min_lat,max_lon,max_lat. |
bbox=37.5074,55.6807,37.7525,55.8327 |
limit |
integer (1–100) | нет | 10 | Максимальное число объектов в ответе. | limit=1 |
fields |
string | нет | — | Поля ответа: address_details, address, pin, bbox, geometry, type, ref. |
fields=address,pin,type |
admin_level |
integer (1–5) | нет | 5 | Ограничение по административному уровню. | admin_level=3 |
geometry |
enum | нет | full |
Детализация геометрии: none, full, packed6. |
geometry=none |
types |
string | нет | — | Фильтр по типам объектов. | types=suburb,locality |
format |
enum | нет | default |
Формат ответа: default или geojson. |
format=geojson |
| Поле | Тип | Описание |
|---|---|---|
request |
string | Строка исходного запроса |
results |
array | Массив доминирующих объектов |
Каждый элемент results аналогичен формату ответа /api/search. Добавляется поле:
| Поле | Тип | Описание | Версия |
|---|---|---|---|
osm_link |
string | Ссылка на объект в OpenStreetMap | v5 |
Запрос:
/api/dominant?bbox=37.5074,55.6807,37.7525,55.8327&limit=1&fields=address_details,address,pin,bbox,geometry,type
Ответ:
{
"request": "/api/dominant?bbox=37.5074,55.6807,37.7525,55.8327&limit=1&...",
"results": [
{
"address": "Россия, Москва, Центральный административный округ, Москва, Пресненский",
"address_details": {
"country": "Россия",
"locality": "Москва",
"region": "Москва",
"subregion": "Центральный административный округ",
"suburb": "Пресненский"
},
"bbox": [37.51393, 55.744396, 37.60976, 55.775521],
"geometry": {
"coordinates": [[[37.538253, 55.796822], ["..."]]],
"type": "MultiPolygon"
},
"pin": [37.560657, 55.762215],
"type": "suburb"
}
]
}
Запрос:
/api/dominant?bbox=37.5074,55.6807,37.7525,55.8327&limit=1&fields=address,pin,type,osm_link
{
"openapi": "3.0.0",
"info": {
"title": "Геокодер — Dominant API",
"version": "5.0.0"
},
"paths": {
"/api/dominant": {
"get": {
"summary": "Доминирующий объект (v3)",
"description": "Возвращает геообъекты, доминирующие во viewport пользователя.",
"tags": ["Dominant"],
"parameters": [
{
"name": "bbox",
"in": "query",
"required": true,
"description": "Границы viewport: min_lon,min_lat,max_lon,max_lat",
"schema": { "type": "string", "example": "37.5074,55.6807,37.7525,55.8327" }
},
{
"name": "limit",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }
},
{
"name": "fields",
"in": "query",
"schema": {
"type": "string",
"example": "address,pin,bbox,geometry,type",
"enum": ["address_details", "address", "pin", "bbox", "geometry", "entrances", "type", "ref", "user_pin"]
}
},
{
"name": "admin_level",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5 }
},
{
"name": "geometry",
"in": "query",
"schema": { "type": "string", "enum": ["none", "full", "packed6"], "default": "full" }
},
{
"name": "types",
"in": "query",
"schema": { "type": "string", "example": "suburb,locality" }
},
{
"name": "format",
"in": "query",
"schema": { "type": "string", "enum": ["default", "geojson"], "default": "default" }
}
],
"responses": {
"200": {
"description": "Список доминирующих объектов",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": { "type": "string" },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": { "type": "string" },
"address_details": { "type": "object" },
"bbox": { "type": "array", "items": { "type": "number" } },
"geometry": { "type": "object" },
"pin": { "type": "array", "items": { "type": "number" } },
"type": { "type": "string" }
}
}
}
}
}
}
}
},
"400": {
"description": "Некорректный запрос",
"content": {
"application/json": {
"example": { "error": "Bad request", "request": "/api/dominant?bbox=-200,-100,200,100" }
}
}
}
}
}
},
"/api/dominant": {
"get": {
"summary": "Доминирующий объект (v5)",
"description": "Актуальная версия. Добавлено поле osm_link в ответе.",
"tags": ["Dominant"],
"parameters": [
{
"name": "bbox",
"in": "query",
"required": true,
"schema": { "type": "string", "example": "37.5074,55.6807,37.7525,55.8327" }
},
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } },
{ "name": "fields", "in": "query", "schema": { "type": "string" } },
{ "name": "admin_level", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } },
{ "name": "geometry", "in": "query", "schema": { "type": "string", "enum": ["none", "full", "packed6"] } },
{ "name": "types", "in": "query", "schema": { "type": "string" } },
{ "name": "format", "in": "query", "schema": { "type": "string", "enum": ["default", "geojson"] } }
],
"responses": {
"200": { "description": "Список доминирующих объектов с полем osm_link" },
"400": { "description": "Некорректный запрос" }
}
}
}
}
}