# Yandex Maps API — place search, business detail and reviews scraper: name, address, phone, website, rating, review count, categories, coordinates and opening hours from Yandex Maps (yandex.com.tr) across Turkey, Russia and the CIS — plus paginated customer reviews, geo-anchored nearby search and address geocoding, no API key required

> Search Yandex Maps for businesses by text/category. Returns up to ~25 orgs with name, address, coordinates, rating, review count, categories, phone, website, social links and opening hours.
> ReefAPI engine `yandex-maps` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/yandex-maps/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /yandex-maps/v1/search — 1 credit
Search Yandex Maps for businesses by text/category. Returns up to ~25 orgs with name, address, coordinates, rating, review count, categories, phone, website, social links and opening hours.

**Parameters:**
- `text` (string, required) — What to look for — a business name, brand or category ('kahve', 'eczane', 'Starbucks', 'restaurant').
- `city` (string, optional) — City slug to scope the search (istanbul, moscow, ankara…). Defaults to Istanbul. Pair with region_id for precise routing.
- `region_id` (string, optional) — Advanced: Yandex internal region id (213=Moscow, 103705=Istanbul). Routes the search geographically; the city slug is cosmetic.
- `ll` (string, optional) — Map-center bias as 'lon,lat' (NOTE: lon first). Strongly recommended for local results.
- `z` (integer, optional, default 14) — Zoom level 1-21 (higher = tighter local area).

**Returns:** orgs[]{org_id, name, address, latitude, longitude, url, rating, rating_count, review_count, categories[], phones[], website, social_links[], hours_text, status, seoname}

**Example request body:**
```json
{
  "text": "kahve",
  "region_id": "103705",
  "city": "istanbul"
}
```

### POST /yandex-maps/v1/detail — 1 credit
Full business card for one org by org_id (or a Yandex Maps org URL): name, address, coordinates, rating, categories, phones, website, social links, opening hours, features and photo count.

**Parameters:**
- `org_id` (string, optional) — Yandex Maps org id (the number in /maps/org/<id>/). From a search result's org_id.
- `url` (string, optional) — Alternatively a full Yandex Maps org URL.

**Returns:** org{org_id, name, address, latitude, longitude, rating, rating_count, review_count, categories[], phones[], website, social_links[], hours_text, description, country, locality, street, house, features[], photo_count}

**Example request body:**
```json
{
  "org_id": "1242233919"
}
```

### POST /yandex-maps/v1/reviews — 1 credit
Paginated public customer reviews for an org: author handle, level, star rating, text, date and the business's reply. 50 reviews per page — page with `page`; meta.total_pages / meta.review_count tell you how many.

**Parameters:**
- `org_id` (string, required) — Yandex Maps org id to pull reviews for.
- `page` (integer, optional, default 1) — Review page (50 per page). Page until meta.total_pages.

**Returns:** reviews[]{review_id, author, author_level, rating, text, date, business_reply, photo_count} + meta{page, total_pages, review_count}

**Example request body:**
```json
{
  "org_id": "1242233919"
}
```

### POST /yandex-maps/v1/nearby — 1 credit
Find businesses of a category around a coordinate. Returns geo-anchored orgs (same shape as search) closest to the given 'lon,lat' center.

**Parameters:**
- `ll` (string, required) — Center to search around as 'lon,lat' (lon first).
- `text` (string, required) — Category or keyword to find near the center ('eczane', 'atm', 'cafe', 'hastane').
- `z` (integer, optional, default 16) — Zoom (tighter = smaller radius).

**Returns:** orgs[]{org_id, name, address, latitude, longitude, rating, review_count, categories[], phones[], hours_text} (closest first)

**Example request body:**
```json
{
  "ll": "28.985,41.036",
  "text": "eczane"
}
```

### POST /yandex-maps/v1/geocode — 1 credit
Geocode an address/place name to coordinates via Yandex. Returns the matched toponym with latitude/longitude and a normalized address. Pass a complete address; Yandex resolves it directly (don't over-qualify a place already named).

**Parameters:**
- `address` (string, required) — Address or place name to geocode (e.g. 'Taksim Meydanı', 'Red Square Moscow').

**Returns:** result{name, address, latitude, longitude, type, uri}

**Example request body:**
```json
{
  "address": "Taksim Meydanı"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=yandex-maps
- Human docs page: https://reefapi.com/docs/yandex-maps
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt