Геокодер — сервис прямого и обратного геокодирования адресных объектов.
Единая точка входа: /api/search
| Параметр | Тип | Обязательный | Описание | Пример |
|---|---|---|---|---|
q |
string | — | Тело поискового запроса. Для прямого геокодирования — текстовая строка. Для обратного — координаты в формате lat,lon. Также принимает ID объекта. |
q=Москва Арбат 1 / q=55.796668,37.538871 / q=0200000001904886 |
Совет. Для поиска объектов из сервиса Подсказчик можно передать ID найденного объекта в качестве значения
q.
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
lang |
2-char | locale | Язык ответа (код по ISO 639-1). По умолчанию — язык региона, в котором найден объект. | lang=en |
limit |
integer (1–100) | 5 | Максимальное число объектов в ответе. | limit=10 |
fields |
string | — | Список полей в ответе через запятую. Возможные значения: address_details, address, pin, bbox, geometry, entrances, type, ref. |
fields=address,pin,geometry |
admin_level |
integer (1–5) | 5 | Ограничение уровня административной детализации ответа: 1 — страна, 2 — регион, 3 — населённый пункт, 4 — улица, 5 — дом. |
admin_level=3 |
format |
enum | default |
Формат ответа: default или geojson. |
format=geojson |
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
location |
string | — | Координаты опорной точки в формате lat,lon. Результаты будут ранжированы по удалённости от неё. |
location=55.796668,37.538871 |
isocode |
2-char | — | Двухбуквенный код страны по ISO 3166-1 alpha-2. Ограничивает поиск указанной страной. | isocode=RU |
types |
string | — | Список типов объектов через запятую. Доступные типы можно получить из /api/types. |
types=shop/food/bakery |
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
radius |
integer (м) | — | Радиус поиска в метрах относительно координат из параметра q. При малом радиусе объект может не найтись. |
radius=300 |
Ответ всегда в формате JSON.
| Поле | Тип | Описание |
|---|---|---|
request |
string | Строка исходного запроса |
results |
array | Массив найденных объектов |
status |
object | Служебная информация о статусе запроса |
Каждый объект в results может содержать:
| Поле | Тип | Описание | Пример |
|---|---|---|---|
address |
string | Полный адрес одной строкой | "Россия, Москва, Ленинградский проспект, 39 с14" |
address_details |
object | Детальная информация об адресе | см. ниже |
pin |
[lon, lat] | Координаты объекта (долгота, широта) | [37.538851, 55.796731] |
bbox |
[minLon, minLat, maxLon, maxLat] | Ограничивающий прямоугольник объекта | [37.538253, 55.796405, 37.539368, 55.79694] |
geometry |
object | Геометрия объекта в формате GeoJSON | {"type": "Polygon", "coordinates": [...]} |
entrances |
array | Входы/выходы здания | см. ниже |
type |
string | Тип объекта (building, street, locality, …) |
"building" |
ref |
hex | ID объекта (нестабильный, может изменяться) | "1000000C4D63818" |
Детализированный разбор адреса.
| Поле | Тип | Описание | Пример |
|---|---|---|---|
country |
string | Страна | "Россия" |
isocode |
2-char | Код страны по ISO 3166-1 alpha-2 | "RU" |
region |
string | Регион / область | "Москва" |
subregion |
string | Административный район | "Северный административный округ" |
locality |
string | Населённый пункт | "Москва" |
sublocality |
string | Микрорайон или жилой комплекс | "Сокол" |
street |
string | Улица | "Ленинградский проспект" |
building |
string | Номер дома, строения или корпуса | "39 с14" |
suburb |
string | Район/микрорайон населённого пункта | "Хорошёвский" |
postal_code |
string | Почтовый индекс | "125167" |
Примечание. Поля
countryиisocodeвременно отключены в некоторых ответах.
| Поле | Тип | Описание |
|---|---|---|
type |
string | Тип геометрии: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon |
coordinates |
array | Массив точек (долгота, широта), описывающий геометрию объекта |
Информация о входах/выходах здания (возвращается при fields=entrances).
| Поле | Тип | Описание |
|---|---|---|
pin |
[lat, lon] | Координаты входа/выхода |
name |
string | Номер подъезда |
flats |
string | Диапазон квартир в подъезде |
type |
string | Тип входа: main — главный, exit — только выход, service — служебный, emergency — аварийный, staircase — парадная/лестница |
wheelchare |
string | Доступность для маломобильных групп: yes, no, limited |
Если по запросу ничего не найдено:
{
"results": [],
"request": "/api/search?limit=1&q=несуществующий+адрес"
}
Запрос:
/api/search?q=Москва Ленинградский 39 14&fields=address_details,address,pin,bbox,geometry,type&limit=1
Ответ:
{
"request": "/api/search?limit=1&q=Москва Ленинградский 39 с14&fields=address_details,address,pin,bbox,geometry,type",
"results": [
{
"address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с14",
"address_details": {
"building": "39 с14",
"country": "Россия",
"postal_code": "125167",
"isocode": "RU",
"locality": "Москва",
"region": "Москва",
"street": "Ленинградский проспект",
"subregion": "Северный административный округ",
"suburb": "Хорошёвский"
},
"bbox": [37.538253, 55.796405, 37.539368, 55.79694],
"geometry": {
"coordinates": [[[37.538253, 55.796822], [37.539204, 55.796405], [37.539368, 55.796523], ["..."]]],
"type": "Polygon"
},
"pin": [37.538851, 55.796731],
"type": "building"
}
]
}
Запрос:
/api/search?q=55.796668,37.538871&fields=address_details,address,pin,bbox,geometry,type&limit=1
Ответ:
{
"request": "/api/search?limit=1&q=55.796668,37.538871&fields=address_details,address,pin,bbox,geometry,type",
"results": [
{
"address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с14",
"address_details": {
"building": "39 с14",
"country": "Россия",
"isocode": "RU",
"locality": "Москва",
"region": "Москва",
"street": "Ленинградский проспект",
"subregion": "Северный административный округ",
"suburb": "Хорошёвский"
},
"bbox": [37.538253, 55.796405, 37.539368, 55.79694],
"geometry": {
"coordinates": [[[37.538253, 55.796822], ["..."]]],
"type": "Polygon"
},
"pin": [37.538851, 55.796731],
"type": "building"
}
]
}
{
"openapi": "3.0.0",
"info": {
"title": "Геокодер — Search API",
"version": "5.0.0"
},
"paths": {
"/api/search": {
"get": {
"summary": "Геокодирование (v3)",
"description": "Прямое и обратное геокодирование адресных объектов.",
"tags": ["Search"],
"parameters": [
{
"name": "q",
"in": "query",
"description": "Текстовый запрос (для прямого) или координаты lat,lon (для обратного геокодирования). Также принимает ID объекта.",
"schema": { "type": "string" },
"examples": {
"forward": { "value": "Москва Ленинградский проспект 39", "summary": "Прямое геокодирование" },
"reverse": { "value": "55.796668,37.538871", "summary": "Обратное геокодирование" },
"by_id": { "value": "0200000001904886", "summary": "По ID объекта" }
}
},
{
"name": "lang",
"in": "query",
"description": "Язык ответа (2-буквенный код ISO 639-1). По умолчанию — язык региона объекта.",
"schema": { "type": "string", "example": "ru" }
},
{
"name": "limit",
"in": "query",
"description": "Максимальное количество объектов в ответе (1–100).",
"schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5, "example": 10 }
},
{
"name": "fields",
"in": "query",
"description": "Список возвращаемых полей через запятую.",
"schema": {
"type": "string",
"example": "address,address_details,pin,bbox,geometry,type",
"enum": ["address_details", "address", "pin", "bbox", "geometry", "entrances", "type", "ref"]
}
},
{
"name": "admin_level",
"in": "query",
"description": "Максимальный административный уровень результатов: 1=страна, 2=регион, 3=город, 4=улица, 5=дом.",
"schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5, "example": 3 }
},
{
"name": "location",
"in": "query",
"description": "Координаты опорной точки lat,lon для ранжирования по близости.",
"schema": { "type": "string", "example": "55.796668,37.538871" }
},
{
"name": "isocode",
"in": "query",
"description": "Код страны по ISO 3166-1 alpha-2 для ограничения поиска.",
"schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "RU" }
},
{
"name": "radius",
"in": "query",
"description": "Радиус поиска в метрах (для обратного геокодирования).",
"schema": { "type": "integer", "minimum": 0, "example": 300 }
},
{
"name": "format",
"in": "query",
"description": "Формат ответа: default или geojson.",
"schema": { "type": "string", "enum": ["default", "geojson"], "default": "default" }
}
],
"responses": {
"200": {
"description": "Список найденных объектов",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": { "type": "string", "description": "Строка исходного запроса" },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": { "type": "string" },
"address_details": { "type": "object" },
"pin": { "type": "array", "items": { "type": "number" } },
"bbox": { "type": "array", "items": { "type": "number" } },
"geometry": { "type": "object" },
"type": { "type": "string" },
"ref": { "type": "string" }
}
}
}
}
}
}
}
},
"400": {
"description": "Некорректный запрос",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": { "type": "string" },
"request": { "type": "string" }
}
}
}
}
}
}
}
},
"/api/search": {
"get": {
"summary": "Геокодирование (v4)",
"description": "Расширенная версия поиска. Аналогична v3, добавлена поддержка типов объектов и улучшено ранжирование.",
"tags": ["Search"],
"parameters": [
{ "name": "q", "in": "query", "schema": { "type": "string" } },
{ "name": "lang", "in": "query", "schema": { "type": "string", "example": "ru" } },
{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 } },
{ "name": "fields", "in": "query", "schema": { "type": "string" } },
{ "name": "admin_level", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5 } },
{ "name": "location", "in": "query", "schema": { "type": "string" } },
{ "name": "isocode", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } },
{ "name": "radius", "in": "query", "schema": { "type": "integer" } },
{ "name": "types", "in": "query", "description": "Фильтр по типам объектов.", "schema": { "type": "string" } },
{ "name": "format", "in": "query", "schema": { "type": "string", "enum": ["default", "geojson"], "default": "default" } }
],
"responses": {
"200": { "description": "Список найденных объектов" },
"400": { "description": "Некорректный запрос" }
}
}
},
"/api/search": {
"get": {
"summary": "Геокодирование (v5)",
"description": "Актуальная версия поиска. Добавлены поля osm_link и дополнительные метаданные.",
"tags": ["Search"],
"parameters": [
{ "name": "q", "in": "query", "schema": { "type": "string" } },
{ "name": "lang", "in": "query", "schema": { "type": "string", "example": "ru" } },
{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 } },
{ "name": "fields", "in": "query", "schema": { "type": "string" } },
{ "name": "admin_level", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5 } },
{ "name": "location", "in": "query", "schema": { "type": "string" } },
{ "name": "isocode", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } },
{ "name": "radius", "in": "query", "schema": { "type": "integer" } },
{ "name": "types", "in": "query", "schema": { "type": "string" } },
{ "name": "format", "in": "query", "schema": { "type": "string", "enum": ["default", "geojson"], "default": "default" } }
],
"responses": {
"200": { "description": "Список найденных объектов" },
"400": { "description": "Некорректный запрос" }
}
}
}
}
}