Сервис позволяет искать объекты по категориям и типам: кафе, аптеки, банкоматы, парки и т.д. Поддерживает поиск как по текстовому запросу, так и по координатам в заданном радиусе.
| Параметр | Тип | По умолчанию | Описание | Пример |
|---|---|---|---|---|
q |
string | — | Текстовый запрос или координаты lat,lon. Можно не указывать, если задан types. |
q=кофейня / q=55.75,37.62 |
types |
string | — | Список типов объектов через запятую. При использовании q не обязателен. Доступные типы — в /api/types. |
types=shop/food/bakery,cafe |
fields |
string | — | Поля ответа: address_details, address, pin, bbox, geometry, entrances, type, ref. |
fields=address,pin,type |
lang |
2-char | locale | Язык ответа. | lang=ru |
limit |
integer (1–100) | 10 | Максимальное число объектов. | limit=20 |
location |
string | — | Опорная точка lat,lon для поиска и ранжирования по близости. |
location=55.75,37.62 |
radius |
integer (м) | — | Радиус поиска вокруг location. |
radius=1000 |
isocode |
2-char | — | Ограничение страной (ISO 3166-1 alpha-2). | isocode=RU |
Совет. Чтобы найти все пекарни в радиусе 500 м от точки, используйте:
/api/places?types=shop/food/bakery&location=55.75,37.62&radius=500
| Поле | Тип | Описание |
|---|---|---|
request |
string | Строка исходного запроса |
results |
array | Массив найденных мест |
Каждый элемент results аналогичен формату ответа /api/search.
Запрос:
/api/places?types=shop/food/bakery&location=55.75,37.62&radius=500&fields=address,pin,type&limit=5
Ответ:
{
"request": "/api/places?types=shop/food/bakery&location=55.75,37.62&radius=500&...",
"results": [
{
"address": "Россия, Москва, ..., улица Арбат, 10",
"pin": [37.601, 55.748],
"type": "shop/food/bakery"
}
]
}
Запрос:
/api/places?q=аптека&location=55.75,37.62&limit=5&fields=address,pin,type
{
"openapi": "3.0.0",
"info": {
"title": "Геокодер — Places API",
"version": "3.0.0"
},
"paths": {
"/api/places": {
"get": {
"summary": "Поиск мест интереса",
"description": "Поиск POI по категории, типу или текстовому запросу с поддержкой геопривязки.",
"tags": ["Places"],
"parameters": [
{
"name": "q",
"in": "query",
"description": "Текстовый запрос или координаты lat,lon. Необязателен при наличии параметра types.",
"schema": { "type": "string", "example": "кофейня" }
},
{
"name": "types",
"in": "query",
"description": "Типы объектов через запятую. Актуальный список типов см. в /api/types.",
"schema": { "type": "string", "example": "shop/food/bakery,cafe" }
},
{
"name": "fields",
"in": "query",
"description": "Поля ответа через запятую",
"schema": {
"type": "string",
"example": "address,pin,type",
"enum": ["address_details", "address", "pin", "bbox", "geometry", "entrances", "type", "ref"]
}
},
{
"name": "lang",
"in": "query",
"schema": { "type": "string", "example": "ru" }
},
{
"name": "limit",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "example": 20 }
},
{
"name": "location",
"in": "query",
"description": "Опорная точка lat,lon для ранжирования по близости",
"schema": { "type": "string", "example": "55.75,37.62" }
},
{
"name": "radius",
"in": "query",
"description": "Радиус поиска в метрах относительно location",
"schema": { "type": "integer", "example": 1000 }
},
{
"name": "isocode",
"in": "query",
"schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "RU" }
}
],
"responses": {
"200": {
"description": "Список мест интереса",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"request": { "type": "string" },
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": { "type": "string" },
"pin": { "type": "array", "items": { "type": "number" } },
"type": { "type": "string" },
"ref": { "type": "string" }
}
}
}
}
},
"example": {
"request": "/api/places?types=shop/food/bakery&location=55.75,37.62&radius=500",
"results": [
{
"address": "Россия, Москва, ..., Арбат 10",
"pin": [37.601, 55.748],
"type": "shop/food/bakery"
}
]
}
}
}
},
"400": { "description": "Некорректный запрос" }
}
}
}
}
}