# Yandex Maps Scraper - Emails, Phones & Reviews (`trakk/yandex-maps-scraper`) Actor

Turn Yandex Maps into structured business leads. Extract phones, emails, websites, social links, reviews, ratings, opening hours and menu prices. Search by keyword, URL or business ID. Supports 6 languages and regional currencies. Export to Excel, CSV or JSON.

- **URL**: https://apify.com/trakk/yandex-maps-scraper.md
- **Developed by:** [Kelopr\_bk](https://apify.com/trakk) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 1,000 business or reviews

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🗺️ Yandex Maps Scraper

#### Организации, контакты, отзывы и цены — в одном датасете

Собирайте данные Яндекс Карт по поисковым запросам, ссылкам и ID организаций. Получайте структурированные карточки, изучайте отзывы и выгружайте результаты в **Excel, CSV или JSON**.

**📍 Организации · ☎️ Телефоны · ✉️ Email · 💬 Отзывы · 🖼️ Медиа · 🍽️ Меню**

[Открыть в Apify Console](https://console.apify.com/actors/AMU5bVbmesSwAbRhF) · [Быстрый старт](#bystryj-start) · [Примеры настроек](#primery-nastroek) · [Запуск через API](#zapusk-cherez-api) · [English quick start](#english-quick-start)

***

### Быстрый старт

1. **Откройте актор** в Apify Console.
2. Перейдите в **Input**. В интерфейсе владельца это **Source → Input**.
3. В **What to collect** выберите **Find businesses**.
4. В **Search queries** введите запрос, например `кофейни Казань`.
5. Укажите количество результатов в **Maximum output rows** и выберите **Язык данных / Data language**.
6. Нажмите **Start** или **Save & start**.
7. Откройте **Output**, выберите нужную вкладку и нажмите **Export**.

> **Для первого запуска:** запрос `кофе Москва`, 3 результата, язык **Русский**. Контакты и отзывы уже включены в стандартной форме.

**Короткий маршрут:** Input → Start → Output → Export.

### Что вы получаете

| Данные | Содержание | Основные поля |
| --- | --- | --- |
| 📍 **Организация** | Название, адрес, категории, координаты, рейтинг | `businessId`, `title`, `address`, `categories`, `latitude`, `longitude`, `rating` |
| ☎️ **Контакты** | Телефоны карточки и сайта, опубликованные email, сайты и мессенджеры | `phones`, `phonesNormalized`, `websitePhones`, `emails`, `websites`, `socialLinks` |
| 💬 **Отзывы** | Текст, оценка, дата, автор, реакции и ответ организации | `reviews`, `reviewId`, `text`, `date`, `authorName`, `businessComment` |
| 🍽️ **Меню и цены** | Позиции меню или прайса, стоимость и валюта источника | `menu`, `price`, `priceValue`, `currency`, `currencyCode` |
| 🖼️ **Медиа** | Фотографии, публикации, видео и логотип | `photos`, `posts`, `videos`, `logoUrl` |
| 🕒 **Информация о месте** | График работы, удобства, метро и остановки рядом | `workingHoursText`, `schedule`, `features`, `nearbyMetro`, `nearbyStops` |
| 🔗 **Источники** | Ссылки на карточку и страницы, где найдены контакты | `sourceUrl`, `contactSources`, `fieldSources`, `scrapedAt` |

Телефоны из Яндекс Карт и телефоны бизнес-сайта представлены отдельно. Для дополнительных контактов сохраняется страница-источник — удобно проверять данные перед добавлением в CRM.

### Как работает актор

**Вы задаёте источник → актор находит карточки → собирает выбранные данные → сохраняет готовые результаты.**

1. Поисковые фразы находят организации в выбранном городе или районе. Ссылки и ID открывают конкретные карточки.
2. Актор читает опубликованные сведения об организации: адрес, телефоны, рейтинг, график и категории.
3. Включённые настройки добавляют отзывы, меню, фотографии, публикации и контакты бизнес-сайта.
4. При включённой дедупликации одна организация сохраняется один раз, даже если встретилась в нескольких запросах.
5. Готовые карточки появляются в датасете по мере обработки. В режиме отзывов каждая строка представляет отдельный отзыв.

### Выберите сценарий

| Задача | Выбор в форме | `scrapeType` | Что будет в одной строке |
| --- | --- | --- | --- |
| Найти организации по запросу | **Find businesses** | `search` | Карточка организации |
| Получить данные известных мест | **Business details from URLs or IDs** | `details` | Карточка организации |
| Собрать отзывы для анализа | **Reviews — one row per review** | `reviews` | Отзыв с данными организации |

**Город можно указать прямо в запросе** — `стоматология Казань` — или отдельно в **Location**. В последнем случае название города добавляется к каждой поисковой фразе.

### Примеры настроек

Эти примеры можно вставить во вкладку **Input → JSON** или сохранить в файл `input.json` для запуска через API.

#### ☕ Кофейни Казани с телефонами

```json
{
  "scrapeType": "search",
  "query": ["кофейни Казань"],
  "maxItems": 20,
  "language": "ru",
  "requirePhone": true,
  "minRating": 4.5,
  "enrichContacts": true,
  "includeReviews": true,
  "maxReviews": 5
}
```

#### 📌 Конкретные организации: контакты, меню и фотографии

```json
{
  "scrapeType": "details",
  "businessIds": ["1036014863", "17323657526"],
  "maxItems": 2,
  "language": "ru",
  "enrichContacts": true,
  "includeMenu": true,
  "includeReviews": true,
  "maxReviews": 5,
  "maxPhotos": 3,
  "maxPosts": 3
}
```

Вместо ID можно заполнить **Yandex Maps links**:

```json
{
  "scrapeType": "details",
  "startUrls": [
    {
      "url": "https://yandex.ru/maps/org/tanuki/1036014863/"
    }
  ],
  "maxItems": 1,
  "language": "ru",
  "includeMenu": true
}
```

#### 💬 Свежие отзывы отеля — отдельными строками

```json
{
  "scrapeType": "reviews",
  "businessIds": ["17323657526"],
  "maxItems": 50,
  "maxReviews": 50,
  "reviewSort": "newest",
  "language": "ru"
}
```

Такой формат удобно экспортировать в Excel: текст, оценка, дата, автор и ответ организации находятся в отдельных столбцах.

### Настройки под вашу задачу

| Настройка | Что делает |
| --- | --- |
| `query` | Поисковые фразы: одна фраза на элемент списка |
| `location` | Город или район, добавляемый к запросам |
| `startUrls` / `businessIds` | Прямой выбор организаций по ссылкам или ID |
| `maxItems` | Количество строк для всего запуска: организаций либо отзывов, в зависимости от сценария |
| `language` | Язык метаданных |
| `enrichContacts` | Дополнительные контакты из бизнес-сайта и ответов организации |
| `includeReviews` / `maxReviews` | Сбор отзывов и их количество на организацию |
| `reviewSort` | Порядок отзывов: `relevance`, `newest`, `highest`, `lowest` |
| `reviewsSince` | Отзывы с датой источника позже указанного момента, например `2026-01-01T00:00:00Z` |
| `includeMenu` | Меню или прайс организации |
| `maxPhotos` / `maxPosts` | Количество фотографий и публикаций на карточку |
| `requirePhone` / `requireWebsite` | Отбор организаций с телефоном или сайтом |
| `minRating` | Минимальная оценка организации; в режиме отзывов — оценка отзыва |
| `filterOpenNow` | Организации, отмеченные источником как открытые сейчас |
| `deduplicate` | Удаление повторяющихся организаций или отзывов |
| `excludeBusinessIds` | Пропуск организаций, которые уже есть в вашей базе |

Поисковые фразы обрабатываются по очереди и используют общее значение `maxItems`.

### 🌐 Языки и региональная валюта

В **Язык данных / Data language** доступны:

| Язык | Значение для API |
| --- | --- |
| **Русский** — по умолчанию | `ru` |
| English | `en` |
| Türkçe | `tr` |
| Қазақша | `kk` |
| Українська | `uk` |
| Azərbaycanca | `az` |

Язык применяется к адресам, категориям и другим метаданным, которые Яндекс выдаёт в выбранной локализации. Оригинальный текст отзыва сохраняется в `text`, а оригинал на выбранном языке или предоставленный Яндексом перевод — в `textInRequestedLanguage`.

**Валюта относится к цене организации и сохраняется при смене языка.** Например, выбор английского для московской карточки оставляет рубли, а выбор русского для алматинской — тенге.

| Цена источника | Код валюты |
| --- | --- |
| ₽ — российский рубль | `RUB` |
| ₸ — казахстанский тенге | `KZT` |
| Br — белорусский рубль | `BYN` |
| ₺ / турецкая лира | `TRY` |

В меню сохраняются исходные `price` и `currency`; для обработки добавлены `priceValue`, `currencyRaw` и `currencyCode`. Поле `currencies` содержит обнаруженные коды валют. Суммы остаются в валюте источника, без пересчёта по курсу.

### Пример результата

Сокращённый фрагмент реальной тестовой карточки:

```json
{
  "businessId": "69353267050",
  "title": "Surf Coffee x Flow",
  "address": "Москва, Страстной бул., 8А",
  "phones": [
    "+7 (993) 337-56-86"
  ],
  "emails": [
    "hello@surfcoffee.ru"
  ],
  "website": "https://surfcoffee.ru/",
  "currency": "RUB",
  "menu": {
    "items": [
      {
        "title": "Пирожное Картошка классическая",
        "price": "195",
        "currency": "₽",
        "currencyCode": "RUB"
      }
    ]
  }
}
```

### 📊 Просмотр и экспорт

В **Output** данные распределены по вкладкам:

| Вкладка | Для чего использовать |
| --- | --- |
| **Businesses** | Список организаций: адреса, оценки, контакты и валюта |
| **Contacts** | Работа с телефонами, email, сайтами и мессенджерами |
| **Reviews** | Анализ отзывов и ответов организации |
| **Photos, posts & menus** | Медиа, публикации и прайсы |
| **Location & features** | География, график работы и характеристики места |
| **Sources & collection status** | Проверка источников и сведений о сборе |

Нажмите **Export** и выберите **Excel**, **CSV** или **JSON**. Для анализа отзывов в таблицах выбирайте сценарий **Reviews — one row per review**. Для сохранения структуры карточки вместе с меню и медиа используйте JSON.

#### Продолжение выгрузки организаций

1. Откройте **Storage → Key-value store** завершённого запуска.
2. Откройте запись **RESUME\_INPUT**.
3. Скопируйте её JSON в **Input** нового запуска.
4. Нажмите **Start**.

Продолжение использует сохранённую позицию поиска и исключает уже записанные ID. Итоги обработки находятся в записи **OUTPUT** того же хранилища.

Для готовых интеграций в **Export field format** предусмотрены `extended`, `zen` и `mamaev`. Они позволяют выбрать нужное представление полей при работе с существующими таблицами и сценариями.

### Запуск через API

API удобно использовать для интеграции с CRM, собственным приложением или обработкой данных на Python.

**1. Установите клиент Apify:**

```bash
pip install apify-client
```

**2. Сохраните один из примеров выше в `input.json`** и передайте API-токен через переменную окружения `APIFY_TOKEN`.

**3. Сохраните этот код в `run_actor.py`:**

```python
import asyncio
import json
import os
from pathlib import Path

from apify_client import ApifyClientAsync


async def main():
    client = ApifyClientAsync(os.environ["APIFY_TOKEN"])
    actor_input = json.loads(
        Path("input.json").read_text(encoding="utf-8-sig")
    )

    run = await client.actor("trakk/yandex-maps-scraper").call(
        run_input=actor_input
    )
    if not run or run["status"] != "SUCCEEDED":
        raise RuntimeError("Check the run details in Apify Console.")

    dataset = await client.dataset(run["defaultDatasetId"]).list_items(
        clean=True
    )
    Path("results.json").write_text(
        json.dumps(dataset.items, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    print(f"Saved {len(dataset.items)} records to results.json")


if __name__ == "__main__":
    asyncio.run(main())
```

**4. Укажите токен и запустите скрипт:**

Windows — PowerShell:

```powershell
$env:APIFY_TOKEN = "YOUR_APIFY_TOKEN"
py run_actor.py
```

macOS / Linux:

```bash
export APIFY_TOKEN="YOUR_APIFY_TOKEN"
python run_actor.py
```

Замените `YOUR_APIFY_TOKEN` своим токеном из настроек Apify. Скрипт запускает актор, ожидает завершения и сохраняет датасет в `results.json` с читаемым Unicode.

***

### English quick start

**Collect Yandex Maps businesses, published contacts, reviews, photos, posts and menu prices in a structured dataset.**

1. [Open the Actor in Apify Console](https://console.apify.com/actors/AMU5bVbmesSwAbRhF) and go to **Input**.
2. Choose **Find businesses**, enter a query such as `coffee Moscow`, and set **Maximum output rows**.
3. Select your **Data language** and the data you want to collect.
4. Click **Start**, then open **Output**.
5. Use **Export** to download Excel, CSV or JSON.

Use `search` for queries, `details` for business links or IDs, and `reviews` for one review per row. The JSON examples above can be pasted directly into the input editor; set `language` to `en` for English metadata.

`maxItems` is the row count for the entire run. `maxReviews` controls reviews per business. Contact evidence is available in `contactSources`; business-site phone numbers are separated into `websitePhones`.

Prices retain their original currency when the data language changes. Source-provided review translations are returned separately from the original text. For repeat business collections, use the generated **RESUME\_INPUT** record or provide previously collected IDs in `excludeBusinessIds`.

The Python example above starts the Actor through the Apify API and saves its output locally.

# Actor input Schema

## `scrapeType` (type: `string`):

Find businesses, enrich specific places, or export one row per review.

## `query` (type: `array`):

One search phrase per line. Include the city in each query, or set Location below. Commas are kept as part of the phrase. Example: coffee Moscow; стоматология Казань.

## `location` (type: `string`):

Appended to every query. Leave empty when your query already includes the city. Coordinates take precedence for the search area.

## `startUrls` (type: `array`):

Business pages, search links, category pages or short share links. Business IDs work below too. Category pages return the organizations available on that page.

## `businessIds` (type: `array`):

Numeric IDs from the business URL, for example 1036014863. Use this to skip discovery.

## `maxItems` (type: `integer`):

TOTAL for the whole run, shared by all queries and URLs. In review mode this limits review rows. Duplicates and filtered places do not use the allowance. Unlimited runs are not supported.

## `language` (type: `string`):

Выберите язык адресов, категорий и графика работы. Названия организаций и отзывы сохраняют оригинал; перевод отзыва возвращается только если его предоставляет Яндекс. Валюта берётся из цен источника и не меняется при выборе языка. / Choose the metadata language. Currency always follows the source prices, without conversion.

## `enrichContacts` (type: `boolean`):

Collect emails, phone links and social profiles from the linked business website (up to three public pages). Official business replies can also provide emails. Every additional contact includes its source. Availability varies.

## `includeMenu` (type: `boolean`):

Fetch the complete menu/price list when the business publishes one. When off, the available menu preview is returned.

## `maxPhotos` (type: `integer`):

Maximum photos to return, including dimensions, tags and available author information. 0 disables photo collection.

## `maxPosts` (type: `integer`):

Maximum public news/posts per business. 0 disables post collection.

## `includeReviews` (type: `boolean`):

Collect review text, rating, date, author profile, photos, videos and the business reply when available.

## `maxReviews` (type: `integer`):

Maximum matching reviews per business. Review mode also respects Maximum output rows across the whole run. 0 disables reviews in business modes.

## `reviewSort` (type: `string`):

Choose the source review order. A pinned review may still appear first.

## `reviewsSince` (type: `string`):

Exclusive cutoff: only reviews dated after this instant. ISO-8601 such as 2026-01-01T00:00:00Z, Unix seconds or milliseconds. An empty result can be correct; Run summary explains it.

## `minRating` (type: `number`):

0 means any rating. Filters business ratings in business modes and review ratings in review mode.

## `maxReviewRating` (type: `integer`):

Used only in Reviews mode. Combine with Minimum rating to select negative or positive reviews.

## `requirePhone` (type: `boolean`):

Keep businesses with a phone listed in Yandex Maps.

## `requireWebsite` (type: `boolean`):

Keep businesses with a website listed in Yandex Maps.

## `filterOpenNow` (type: `boolean`):

Keep businesses whose current source status explicitly says they are open.

## `deduplicate` (type: `boolean`):

Return a business once across all sources, or each unique review once in Reviews mode.

## `excludeBusinessIds` (type: `array`):

Useful for repeat runs. These business IDs are skipped before enrichment.

## `outputFormat` (type: `string`):

Extended includes the fields used by popular Yandex Maps Actors plus additional contact evidence and data-quality fields. Choose a compatibility format to match differing website/features/region data types.

## `coordinates` (type: `string`):

Example: 37.622,55.753. Overrides the city center for query searches.

## `viewportSpan` (type: `string`):

Example: 0.1,0.1 for a city-center area. Requires a sensible area center.

## `maxPages` (type: `integer`):

Applies to search and review pagination. The Run summary distinguishes page limits from a fully exhausted source.

## `maxRuntimeSecs` (type: `integer`):

Stops collection gracefully within the time budget and keeps records already saved. Upper limit cannot be raised by input.

## `maxRequests` (type: `integer`):

Total attempts, including retries, detail pages and website contact pages. Stops new work when reached.

## `maxConcurrency` (type: `integer`):

Balanced default for speed and reliability. Use a lower value if the source is responding slowly.

## `maxRetries` (type: `integer`):

Bounded retries for temporary source failures. A failed business does not discard successful results.

## `proxyConfiguration` (type: `object`):

Optional custom connection configuration. Leave unchanged for automatic handling.

## `maxContactPages` (type: `integer`):

Maximum public pages from the business website, including contact pages and a linked privacy page when needed.

## `resumeState` (type: `object`):

Use the value provided in RESUME\_INPUT to continue a limited run. Leave empty for a new collection.

## Actor input object example

```json
{
  "scrapeType": "search",
  "query": [
    "кофе Москва"
  ],
  "location": "",
  "startUrls": [],
  "businessIds": [],
  "maxItems": 3,
  "language": "ru",
  "enrichContacts": true,
  "includeMenu": false,
  "maxPhotos": 3,
  "maxPosts": 3,
  "includeReviews": true,
  "maxReviews": 5,
  "reviewSort": "relevance",
  "reviewsSince": "",
  "minRating": 0,
  "maxReviewRating": 5,
  "requirePhone": false,
  "requireWebsite": false,
  "filterOpenNow": false,
  "deduplicate": true,
  "excludeBusinessIds": [],
  "outputFormat": "extended",
  "coordinates": "",
  "viewportSpan": "",
  "maxPages": 10,
  "maxRuntimeSecs": 150,
  "maxRequests": 300,
  "maxConcurrency": 8,
  "maxRetries": 1,
  "maxContactPages": 3,
  "resumeState": {}
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `contacts` (type: `string`):

No description

## `reviews` (type: `string`):

No description

## `media` (type: `string`):

No description

## `location` (type: `string`):

No description

## `quality` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": [
        "кофе Москва"
    ],
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("trakk/yandex-maps-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": ["кофе Москва"],
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("trakk/yandex-maps-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": [
    "кофе Москва"
  ],
  "maxItems": 3
}' |
apify call trakk/yandex-maps-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,trakk/yandex-maps-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AMU5bVbmesSwAbRhF/builds/ustYXRsX720dhjNMr/openapi.json