POST /v1/maps · /v1/places · /v1/place · engine=yandex
API Яндекс Карт для поиска организаций
Запрос и точка на карте на входе, организации с адресом, координатами, рейтингом, телефонами, сайтом и часами работы в JSON на выходе. Данные Яндекс Карт без своего парсера, прокси и браузера.
Это не JavaScript API Яндекс Карт
Чтобы нарисовать карту на сайте, нужен JavaScript API Яндекс Карт. SerpKite — API данных: он возвращает организации, которые Яндекс Карты показывают по запросу, в JSON для бэкенда, скрипта или агента.
Обзор
Что умеет API Яндекс Карт для поиска организаций
/v1/maps с engine: "yandex" ищет в Яндекс Картах вокруг точки ll (@широта,долгота,zoomz, например @55.757,37.615,14z) или по location. /v1/places делает то же по названию города. Каждый результат — организация: название, рубрики, адрес, координаты, рейтинг и число оценок, телефоны, сайт, часы работы, oid и ссылка на карточку.
Названия, адреса и рубрики приходят в том виде, в каком их показывают Яндекс Карты, по умолчанию на русском. page листает результаты: рейтинг, число оценок и миниатюра есть на первой странице, на следующих — только рейтинг.
Чтобы позже прочитать одну организацию, передайте её oid в /v1/place. В ответе будут yandex_maps_url, структурированные weekly_hours (выходные, круглосуточная работа и интервалы после полуночи указаны явно), телефоны, сайт и фотографии.
Что приходит в ответе
-
results[].titlestring - Название организации.
-
type, typesstring, string[] - Основная рубрика и все рубрики организации.
-
address, countrystring - Адрес и код страны (RU, KZ…).
-
latitude, longitudenumber - Координаты организации.
-
rating, rating_countnumber, integer - Рейтинг и число оценок (число оценок — на первой странице).
-
phone_number, international_phone_numberstring - Телефон в местном и международном формате.
-
websitestring - Сайт организации.
-
opening_hours, weekly_hoursobject - Часы работы строками по дням и те же часы структурировано: интервалы open/close по дням недели.
-
timezone, thumbnail_urlstring - Часовой пояс и миниатюра.
-
oid, yandex_maps_urlstring - ID организации в Яндекс Картах и ссылка на её карточку.
-
metaobject - request_id, credits_used, cached, latency_ms, parse_quality, engine (движок, который ответил) и route (каждая попытка: движок, результат и время в мс).
Запрос
curl https://api.serpkite.com/v1/maps \
-H "Authorization: Bearer $SERPKITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"кофейня","ll":"@55.757,37.615,14z","engine":"yandex"}'Поиск по городу: POST /v1/places
curl https://api.serpkite.com/v1/places \
-H "Authorization: Bearer $SERPKITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"стоматология","location":"Moscow, Russia","engine":"yandex"}'Одна организация по oid: POST /v1/place
curl https://api.serpkite.com/v1/place \
-H "Authorization: Bearer $SERPKITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"oid":"157998496135"}'Ответ (живой ответ, сокращён до двух результатов)
{
"request": {
"country": "us",
"endpoint": "maps",
"engine": "yandex",
"language": "en",
"ll": "@55.757,37.615,14z",
"num": 10,
"page": 1,
"q": "кофейня"
},
"results": [
{
"address": "Мясницкая ул., 13, стр. 21",
"country": "RU",
"international_phone_number": "+79255750577",
"latitude": 55.763213,
"longitude": 37.633405,
"oid": "157998496135",
"opening_hours": {
"Friday": "09:00–22:00",
"Monday": "09:00–22:00",
"Saturday": "10:00–22:00",
"Sunday": "10:00–22:00",
"Thursday": "09:00–22:00",
"Tuesday": "09:00–22:00",
"Wednesday": "09:00–22:00"
},
"phone_number": "+7 (925) 575-05-77",
"position": 1,
"rating": 4.9,
"rating_count": 1568,
"thumbnail_url": "https://avatars.mds.yandex.net/get-altay/19547455/2a0000019ca3b23d14c09f4a6234b53a5c24/L",
"timezone": "Europe/Moscow",
"title": "Ycp",
"type": "Кофейня",
"types": [
"Кофейня",
"кафе",
"быстрое питание"
],
"website": "https://ycp.clients.site/",
"weekly_hours": {
"friday": [
{
"close": "22:00",
"open": "09:00"
}
],
"monday": [
{
"close": "22:00",
"open": "09:00"
}
]
},
"yandex_maps_url": "https://yandex.ru/maps/org/157998496135/"
},
{
"address": "Страстной бул., 8А, Москва",
"country": "RU",
"description": "Кофейня Surf Coffee x Flow — это уютное место, где можно провести время с друзьями или поработать удаленно. Гости отмечают, что в кофейне всегда чисто и быстро можно найти себе место, а персонал очень…",
"international_phone_number": "+79933375686",
"latitude": 55.766219,
"longitude": 37.610433,
"oid": "69353267050",
"opening_hours": {
"Friday": "08:00–23:00",
"Monday": "08:00–23:00",
"Saturday": "10:00–23:00",
"Sunday": "10:00–23:00",
"Thursday": "08:00–23:00",
"Tuesday": "08:00–23:00",
"Wednesday": "08:00–23:00"
},
"phone_number": "+7 (993) 337-56-86",
"position": 2,
"rating": 4.9,
"rating_count": 1261,
"thumbnail_url": "https://avatars.mds.yandex.net/get-altay/15340601/2a000001975930a7923bccd85b1b3c57e1be/L",
"timezone": "Europe/Moscow",
"title": "Surf Coffee x Flow",
"type": "Кофейня",
"types": [
"Кофейня"
],
"website": "https://surfcoffee.ru/",
"weekly_hours": {
"friday": [
{
"close": "23:00",
"open": "08:00"
}
],
"monday": [
{
"close": "23:00",
"open": "08:00"
}
]
},
"yandex_maps_url": "https://yandex.ru/maps/org/69353267050/"
}
],
"meta": {
"request_id": "req_01J8ZK4M6Q2V7",
"credits_used": 1,
"cached": false,
"engine": "yandex",
"route": [
{
"provider": "yandex",
"outcome": "ok",
"ms": 997
}
],
"latency_ms": 1047,
"parse_quality": "ok"
}
}
В каждом ответе есть заголовки X-Credits-Used, X-Credits-Remaining,
X-Cache и X-Tokens-Estimate.
Запустить этот запрос в песочнице
Один ключ, много поисковиков
Яндекс через SerpKite
- Тот же ключ, тот же конверт ответа и тот же вызов SDK, что и для Google: меняется только
engine. meta.engineназывает движок, который ответил, аmeta.routeперечисляет все попытки. Результат никогда не выдаётся за чужой.engine: "auto"оставляет Google первым и переходит к Яндексу последним, только если остальные движки не ответили. Как работает запасной маршрут- SerpKite читает публичные страницы Яндекса без входа в аккаунт и не связан с Яндексом.
Справочник
Параметры
Параметры /v1/maps, /v1/places и /v1/place для Яндекса: в JSON-теле запроса или в строке запроса.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
q
обязательный
|
string | – | Что искать: рубрика или название («кофейня», «стоматология», название сети). Для /v1/place не нужен. |
engine
|
string | string[] | "yandex" — только Яндекс. "auto" сначала пробует Google и переходит к другим движкам, только если он не ответил (Яндекс — последний запасной). Список, например ["google", "yandex"], ограничивает маршрут этими движками. | |
ll
|
string | – | Точка и масштаб карты: "@широта,долгота,zoomz", например "@55.757,37.615,14z" (по умолчанию 14z). Важнее location. |
location
|
string | – | Место поиска текстом, например "Moscow, Russia". Для /v1/places — основной способ задать город. |
page
|
integer | 1 | Страница результатов. Каждая страница оплачивается отдельно. |
oid
|
string | – | Для /v1/place: ID организации в Яндекс Картах (число из yandex.ru/maps/org/…/<oid>/). Подразумевает engine=yandex. |
format
|
string | json | Формат ответа: json, compact (JSON только с полями, нужными агенту) или markdown (готовый текст для LLM). |
fields
|
string | – | Проекция через запятую, например results.title,results.link. Ответ короче, токенов меньше. |
max_age
|
integer | – | Принять результат из кэша не старше N секунд. Попадание в кэш стоит 0.5 кредита вместо 1. |
Полный справочник, коды ошибок и заголовки — в документации по провайдерам (на английском).
Сравнение
Свой парсер Яндекс Карт или SerpKite
Парсинг Яндекс Карт своими силами — это прокси, браузер, капчи и селекторы, которые ломаются после каждого обновления вёрстки. SerpKite берёт это на себя и отдаёт готовый JSON.
| Свой парсер | SerpKite | |
|---|---|---|
| Инфраструктура | Прокси, headless-браузер, ротация и обработка капчи | Один HTTP-запрос с API-ключом |
| Изменения на стороне Яндекса | Парсер ломается, чинить вам | Парсеры и маршруты поддерживаем мы |
| Формат данных | Что извлечёте сами | Единые поля, как у Google Maps: title, address, rating, weekly_hours, oid |
| Оплата | Прокси и серверы, в том числе за неудачные запросы | 1 кредит за страницу, от $0.60 за 1000; неудачные, заблокированные и пустые запросы бесплатны |
| Другие источники | Только Яндекс | Google Maps тем же запросом без engine; engine: "auto" с Яндексом как запасным |
Задачи
Что строят на этом API
Базы организаций
Кофейни, клиники или автосервисы города с телефонами, сайтами и часами работы — для продаж, лидогенерации и CRM.
Локальная аналитика
Сколько конкурентов вокруг точки, какой у них рейтинг и когда они работают: выбор локации и исследование рынка.
Агенты с местными данными
Дайте агенту поиск по организациям России и СНГ через MCP, LangChain или SDK.
Цены
Сколько стоит
Цена запроса
1 кредит
за страницу результатов, как у Google
- От $0.60 за 1000 запросов на крупном пакете, $1.00 на стартовом.
- Кредиты не сгорают. Без подписки.
- За неудачные, пустые и заблокированные запросы кредиты не списываются.
- 2 500 бесплатных кредитов при регистрации, затем 1 000 в месяц.
| Пакет | Цена | За 1000 запросов | Запросов в пакете |
|---|---|---|---|
| Starter | $10 | $1.00 | 10 000 |
| Growth | $50 | $0.80 | 62 500 |
| Pro | $300 | $0.60 | 500 000 |
Вопросы
Частые вопросы
Что ещё почитать
Связанные страницы
Начните сейчас
Ключ за 30 секунд
2 500 бесплатных кредитов, затем 1 000 каждый месяц. Без карты.