Сервис подсказок помогает реализовать автодополнение при посимвольном вводе: по мере того как пользователь набирает адрес или название места, сервис возвращает список наиболее релевантных вариантов.
Отличие от /api/search: Suggest оптимизирован для интерактивного ввода и возвращает краткие подсказки, а не полные карточки объектов. Для получения полных данных после выбора подсказки используйте /api/search с q={ref}.
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
q |
string | — | Тело запроса — частичный адрес или название места. | q=Москва Ленин |
fields |
string | name |
Список возвращаемых полей. Доступные значения зависят от версии (см. ниже). | fields=name,address,ref,type |
lang |
2-char | locale | Язык ответа. | lang=ru |
limit |
integer (1–100) | 10 | Максимальное число подсказок. | limit=5 |
location |
string | — | Координаты опорной точки lat,lon для приоритизации ближайших результатов. |
location=55.75,37.62 |
radius |
integer (м) | — | Радиус поиска вокруг location в метрах. |
radius=5000 |
admin_level |
integer (1–5) | 5 | Максимальный административный уровень: 1=страна, 2=регион, 3=город, 4=улица, 5=дом. | admin_level=4 |
isocode |
2-char | — | Ограничение поиска по стране (ISO 3166-1 alpha-2). | isocode=RU |
types |
string | — | Фильтр по типам объектов (через запятую). Доступные типы — в /api/types. |
types=poi |
| Поле | v3 | v4 | v5 |
|---|---|---|---|
name |
✓ | ✓ | ✓ |
address |
✓ | ✓ | ✓ |
address_details |
✓ | ✓ | ✓ |
ref |
✓ | ✓ | ✓ |
type |
✓ | ✓ | ✓ |
pin |
— | ✓ | ✓ |
distance |
— | ✓ | ✓ |
oref |
— | — | ✓ |
osm_link |
— | — | ✓ |
| Поле | Тип | Описание |
|---|---|---|
request |
string | Строка исходного запроса |
results |
array | Массив подсказок |
Каждый элемент results:
| Поле | Тип | Описание |
|---|---|---|
name |
string | Название объекта (отображаемый заголовок подсказки) |
address |
string | Полный адрес одной строкой |
address_details |
object | Разбор адреса по компонентам (страна, регион, улица…) |
ref |
string | ID объекта для передачи в /search?q={ref} |
type |
string | Тип объекта (building, street, locality, poi…) |
pin |
[lon, lat] | Координаты объекта (v4, v5) |
distance |
number | Расстояние в метрах от location (v4, v5) |
osm_link |
string | Ссылка на объект в OSM (v5) |
Запрос:
/api/suggest?q=Москва Ленинградский 39&limit=3&fields=name,address,ref,type
Ответ:
{
"request": "/api/suggest?limit=3&q=Москва Ленинградский 39&fields=name,address_details,address,ref,type",
"results": [
{
"address": "Россия, Москва, Северный административный округ, Москва, Хорошёвский, Ленинградский проспект, 39 с38",
"address_details": {
"building": "39 с38",
"country": "Россия",
"isocode": "RU",
"locality": "Москва",
"region": "Москва",
"street": "Ленинградский проспект",
"subregion": "Северный административный округ",
"suburb": "Хорошёвский"
},
"ref": "0200000001904886",
"type": "building"
},
{
"address": "Россия, Москва, ..., Ленинградский проспект, 39 с14",
"ref": "...",
"type": "building"
}
]
}
Запрос:
/api/suggest?q=Москва Ленинградский 39&limit=3&fields=name,address,ref,type,pin,distance&location=55.75,37.62
Ответ:
{
"request": "/api/suggest?...",
"results": [
{
"address": "Москва, ..., Ленинградский проспект, 39 с38",
"name": "Спортивный комплекс",
"pin": [37.537796, 55.796228],
"distance": 5200,
"ref": "0200000001904886",
"type": "building"
}
]
}
{
"openapi": "3.0.0",
"info": {
"title": "Геокодер — Suggest API",
"version": "5.0.0"
},
"paths": {
"/api/suggest": {
"get": {
"summary": "Подсказчик адресов (v3)",
"description": "Подсказки при посимвольном вводе адреса или названия места.",
"tags": ["Suggest"],
"parameters": [
{
"name": "q",
"in": "query",
"description": "Частичный текст адреса или названия",
"schema": { "type": "string", "example": "Москва Ленин" }
},
{
"name": "fields",
"in": "query",
"description": "Поля ответа через запятую",
"schema": {
"type": "string",
"example": "name,address,ref,type",
"enum": ["name", "address", "address_details", "ref", "type", "user_pin"]
}
},
{
"name": "lang",
"in": "query",
"schema": { "type": "string", "example": "ru" }
},
{
"name": "limit",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }
},
{
"name": "location",
"in": "query",
"description": "Опорная точка lat,lon для приоритизации ближних результатов",
"schema": { "type": "string", "example": "55.75,37.62" }
},
{
"name": "radius",
"in": "query",
"schema": { "type": "integer", "example": 5000 }
},
{
"name": "admin_level",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5 }
},
{
"name": "isocode",
"in": "query",
"schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "RU" }
},
{
"name": "types",
"in": "query",
"schema": { "type": "string", "example": "poi" }
}
],
"responses": {
"200": {
"description": "Список подсказок",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": { "type": "string" },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"address": { "type": "string" },
"address_details": { "type": "object" },
"ref": { "type": "string" },
"type": { "type": "string" }
}
}
}
}
}
}
}
},
"400": { "description": "Некорректный запрос" }
}
}
},
"/api/suggest": {
"get": {
"summary": "Подсказчик адресов (v4)",
"description": "Расширенная версия подсказчика. Добавлены поля pin и distance.",
"tags": ["Suggest"],
"parameters": [
{ "name": "q", "in": "query", "schema": { "type": "string" } },
{
"name": "fields",
"in": "query",
"schema": {
"type": "string",
"enum": ["name", "address", "address_details", "ref", "type", "pin", "distance"]
}
},
{ "name": "lang", "in": "query", "schema": { "type": "string" } },
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } },
{ "name": "location", "in": "query", "schema": { "type": "string" } },
{ "name": "radius", "in": "query", "schema": { "type": "integer" } },
{ "name": "admin_level", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } },
{ "name": "isocode", "in": "query", "schema": { "type": "string" } },
{ "name": "types", "in": "query", "schema": { "type": "string" } }
],
"responses": {
"200": { "description": "Список подсказок" },
"400": { "description": "Некорректный запрос" }
}
}
},
"/api/suggest": {
"get": {
"summary": "Подсказчик адресов (v5)",
"description": "Актуальная версия. Добавлены поля oref и osm_link.",
"tags": ["Suggest"],
"parameters": [
{ "name": "q", "in": "query", "schema": { "type": "string" } },
{
"name": "fields",
"in": "query",
"schema": {
"type": "string",
"enum": ["name", "address", "address_details", "ref", "type", "pin", "distance", "oref", "osm_link"]
}
},
{ "name": "lang", "in": "query", "schema": { "type": "string" } },
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } },
{ "name": "location", "in": "query", "schema": { "type": "string" } },
{ "name": "radius", "in": "query", "schema": { "type": "integer" } },
{ "name": "admin_level", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } },
{ "name": "isocode", "in": "query", "schema": { "type": "string" } },
{ "name": "types", "in": "query", "schema": { "type": "string" } }
],
"responses": {
"200": { "description": "Список подсказок" },
"400": { "description": "Некорректный запрос" }
}
}
}
}
}