# Yandex Maps Business Search, Details & Reviews Scraper (`nimbryxo-studio/yandex-maps-business-search-details-and-reviews`) Actor

Search Yandex Maps by keyword, fetch full business details, or collect customer reviews - with address, phone, rating, working hours, photos, coordinates, and review text across six regional domains.

- **URL**: https://apify.com/nimbryxo-studio/yandex-maps-business-search-details-and-reviews.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Automation, Lead generation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Yandex Maps Business Search, Details & Reviews Scraper

Pull business data from [Yandex Maps](https://yandex.com/maps/), the map service most used in Russia and widely used across Kazakhstan, Uzbekistan, Belarus and Turkey. Search by keyword, fetch the business card for specific organizations, or collect customer reviews, across six regional domains and eight interface languages.

### What this actor does

- **Three modes:** `searchPlaces` (keyword search), `getDetails` (full business detail by URL), `getReviews` (customer reviews by URL)
- Search results return name, address, rating, review count, categories and photos; detail lookups add coordinates, phone, website and the opening-hours line
- Collects review author, rating, text, date, and likes when scraping reviews
- Filters search results by a minimum star rating, and loads reviews newest first, highest rated first, or in Yandex's default order
- Covers six Yandex domains (`yandex.com`, `.ru`, `.com.tr`, `.kz`, `.uz`, `.by`) and eight UI languages
- Leaves out any field Yandex doesn't show for a business or review, so records only contain fields with values

### Output per record

Every record carries a `recordType` field — `"place"` or `"review"`. If nothing is found for a query or URL, no record is written for it.

#### Place record (`recordType: "place"`, modes `searchPlaces` and `getDetails`)

- `placeId` — Yandex Maps organization ID
- `name`, `url` — business name and Yandex Maps page URL
- `address` — street address as shown by Yandex
- `coordinates` — object `{ lat, lng }` (`getDetails` only)
- `phone`, `website` — contact details (`getDetails` only)
- `rating`, `reviewCount` — star rating and total review count
- `categories` — array of business categories (e.g. `"Coffee shop"`, `"Cafe"`)
- `workingHours` — object keyed by day of week (`getDetails` only); filled when the business card's hours line can be read as a schedule, e.g. a 24-hour business
- `openStatus` — the hours line as Yandex shows it, e.g. "Open until 22:00", when it can't be turned into `workingHours` (`getDetails` only)
- `photos` — array of photo URLs (up to 20 on detail pages; search results return the thumbnails shown in the result card)
- `scrapedAt` — ISO 8601 collection timestamp

#### Review record (`recordType: "review"`)

- `placeId`, `placeName`, `placeUrl` — the business the review belongs to
- `reviewId` — review key, usually the reviewer's profile ID joined with the review date
- `author`, `authorUrl` — reviewer name and profile link
- `rating` — star rating given
- `text` — review text
- `date` — review date (`YYYY-MM-DD` when Yandex provides a machine-readable date)
- `likes` — like count on the review
- `scrapedAt` — ISO 8601 collection timestamp

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `searchPlaces` | `searchPlaces` / `getDetails` / `getReviews` |
| `searchQueries` | array of strings | – | Search queries combining business type and location (mode=`searchPlaces`) |
| `businessUrls` | array of strings | – | Yandex Maps business page URLs (mode=`getDetails` or `getReviews`) |
| `yandexDomain` | string | `yandex.ru` | Regional domain: `yandex.com`, `yandex.ru`, `yandex.com.tr`, `yandex.kz`, `yandex.uz`, `yandex.by` |
| `language` | string | `en` | UI/results language: `en`, `ru`, `tr`, `de`, `fr`, `uk`, `kk`, `uz` |
| `maxItems` | integer | `20` | Maximum places per search query, or reviews per business URL (1–500); not used by `getDetails` |
| `minRating` | string | `any` | Minimum rating filter for `searchPlaces`: `any`, `3`, `3.5`, `4`, `4.5` |
| `reviewsSortOrder` | string | `by_date_desc` | Review sort order for `getReviews`: `by_date_desc`, `by_rating_desc`, `by_relevance` |
| `proxyConfiguration` | object | – | Recommended (the form is prefilled with a residential proxy); Yandex may show a CAPTCHA to data-center IPs |

#### Example: search for coffee shops in Moscow

```json
{
  "mode": "searchPlaces",
  "searchQueries": ["coffee shops Moscow"],
  "minRating": "4",
  "maxItems": 30
}
```

#### Example: full details for a specific business

```json
{
  "mode": "getDetails",
  "businessUrls": ["https://yandex.com/maps/org/shokoladnitsa/123456789/"]
}
```

#### Example: most recent reviews for a business, in Russian

```json
{
  "mode": "getReviews",
  "businessUrls": ["https://yandex.com/maps/org/shokoladnitsa/123456789/"],
  "language": "ru",
  "reviewsSortOrder": "by_date_desc",
  "maxItems": 100
}
```

#### Example: Turkish restaurant search

```json
{
  "mode": "searchPlaces",
  "searchQueries": ["sushi restaurant Istanbul"],
  "yandexDomain": "yandex.com.tr",
  "language": "tr"
}
```

### Use cases

- **Lead generation** — build lists of local businesses with search, then run `getDetails` on them for phone numbers and websites
- **Market research** — survey competitors, ratings, and business density in a city or category
- **Brand monitoring** — find a brand's branches through search and track their customer reviews
- **Site selection** — scan nearby amenities and service density for a potential location
- **Reputation tracking** — pull recent reviews on a schedule to watch sentiment trends

### FAQ

**Can I search any city across Russia and the CIS?**
Yes, as long as Yandex Maps lists businesses there. Include the city name in your search query, e.g. `restaurants Novosibirsk`.

**Does this work for Turkish businesses?**
Yes. Set `yandexDomain` to `yandex.com.tr` and `language` to `tr` for the best results on Turkish locations.

**How many results can one search return?**
Up to `maxItems` (max 500) per query, and each query in `searchQueries` gets its own allowance. The actor keeps loading more results until it reaches that number, Yandex stops returning new businesses, or a scrolling limit is hit, so very broad searches may come back with fewer.

**Can I get reviews in their original language?**
Review text is returned in whatever language the reviewer wrote it. The `language` setting changes the interface language, which affects things like category names and the opening-hours line, not the reviews themselves.

**Is there a cap on reviews per business?**
`maxItems` is applied to each business URL separately, up to 500. The actor stops earlier when a business has fewer reviews or when no new reviews load after scrolling.

**Can I filter search results by rating?**
Yes — use `minRating` to drop businesses below a chosen threshold, e.g. `4.5` for only top-rated places. Businesses without a rating are dropped too whenever a threshold is set. The filter only applies to `searchPlaces`.

**Why does the actor recommend a proxy?**
Yandex Maps may show a CAPTCHA to automated requests from data-center IP addresses; a residential proxy makes that much less likely. In `searchPlaces` mode, if a query hits a CAPTCHA on your chosen domain, the actor tries `yandex.ru`, `yandex.com.tr` and `yandex.uz` before skipping the query.

**Do I need to know a business's URL ahead of time?**
Only for `getDetails` and `getReviews` mode. Use `searchPlaces` first to discover businesses by keyword, then feed their URLs into the other modes.

**Is this affiliated with Yandex?**
No. This is an independent, third-party actor that reads Yandex Maps' public pages; it isn't affiliated with or endorsed by Yandex.

# Actor input Schema

## `mode` (type: `string`):

What to scrape. searchPlaces: search for businesses by keyword. getDetails: fetch full details of specific business URLs. getReviews: scrape reviews from specific business URLs.

## `searchQueries` (type: `array`):

One or more search queries (mode=searchPlaces). Combine business type and location, e.g. 'coffee shops Moscow', 'sushi restaurant Istanbul'.

## `businessUrls` (type: `array`):

Yandex Maps business page URLs (mode=getDetails or getReviews). Format: https://yandex.com/maps/org/{name}/{id}/

## `yandexDomain` (type: `string`):

Yandex Maps regional domain to use.

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

UI and results language.

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

Maximum number of records to return (places or reviews).

## `minRating` (type: `string`):

Filter out places below this rating. Only applies in searchPlaces mode.

## `reviewsSortOrder` (type: `string`):

How to sort reviews. Only applies in getReviews mode.

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

Recommended. Yandex may trigger captcha on datacenter IPs. Residential proxies give best results.

## Actor input object example

```json
{
  "mode": "searchPlaces",
  "searchQueries": [
    "coffee shops Moscow"
  ],
  "businessUrls": [],
  "yandexDomain": "yandex.ru",
  "language": "en",
  "maxItems": 20,
  "minRating": "any",
  "reviewsSortOrder": "by_date_desc",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with scraped Yandex Maps places and reviews

# 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 = {
    "mode": "searchPlaces",
    "searchQueries": [
        "coffee shops Moscow"
    ],
    "businessUrls": [],
    "yandexDomain": "yandex.ru",
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/yandex-maps-business-search-details-and-reviews").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 = {
    "mode": "searchPlaces",
    "searchQueries": ["coffee shops Moscow"],
    "businessUrls": [],
    "yandexDomain": "yandex.ru",
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/yandex-maps-business-search-details-and-reviews").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 '{
  "mode": "searchPlaces",
  "searchQueries": [
    "coffee shops Moscow"
  ],
  "businessUrls": [],
  "yandexDomain": "yandex.ru",
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call nimbryxo-studio/yandex-maps-business-search-details-and-reviews --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/yandex-maps-business-search-details-and-reviews"
        }
    }
}
```

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/YYnETyuUyTTy4DeLE/builds/LIm4dMgkwIbLaBiFp/openapi.json