YandexHow-to

Yandex Maps parser in Python with phones and websites

Export Yandex Maps businesses with phones, websites and social links to CSV in Python. 503 St Petersburg dental clinics came back in 24 calls.

5 min read

Short answer

  • A Python script turns a Yandex Maps search into a CSV of businesses with phones, websites, social links, ratings, hours and coordinates.
  • Yandex's own Organization Search API returns phones and hours but no ratings, and it is sold as a yearly license from $2,750.
  • ToolzerHub's Yandex Maps search returns up to 25 businesses with contacts per call for 1 credit; 503 dental clinics cost 24 credits.
On this page

The script below exports the businesses a Yandex Maps search returns to a CSV with phones, websites, social links, rating, review count, hours and coordinates. Each call returns up to 25 businesses with their contacts already in the row, so you need no second call per business. A search for dental clinics in St Petersburg gave 503 businesses in 24 calls.

What Yandex's own API returns

Yandex's Organization Search API finds businesses by name, address or category, and its documented fields include phones, hours and categories. It has no rating or review count. Access is a yearly license: $2,750 for up to 250,000 requests. If you need a licensed feed at that volume, use it.

What one call returns

We make ToolzerHub. Our Yandex API has a maps/search route that returns up to 25 businesses a page around a point you choose, with contacts in each row. Each call is a GET with the x-api-key header and costs 1 credit.

bash
export TOOLZERHUB_API_KEY=your_key
curl -G -H "x-api-key: $TOOLZERHUB_API_KEY" "https://api.toolzerhub.com/v1/yandex/maps/search" \
  --data-urlencode "query=стоматология" -d latitude=59.9343 -d longitude=30.3351 \
  -d span=0.1 -d language=ru_RU

A St Petersburg clinic from that call, trimmed:

json
{
  "id": "39120098029",
  "title": "Миа.рф",
  "categories": [{ "name": "Стоматологическая клиника", "class": "dental" }],
  "full_address": "Санкт-Петербург, улица Печатника Григорьева, 1",
  "phones": [{ "number": "+7 (812) 213-24-35", "type": "phone", "value": "+78122132435" }],
  "websites": ["https://миа.рф/?calltouch_tm=yd_c:{campaign_id}_gb:{gbid}..."],
  "social_links": [{ "type": "telegram", "href": "https://t.me/miaclinicstom" }],
  "rating": { "value": 4.900000095367432, "ratings": 1019, "reviews": 535 },
  "working_time_text": "ежедневно, 10:00–20:00",
  "latitude": 59.92018,
  "longitude": 30.35255,
  "url": "https://yandex.com/maps/org/mia_rf/39120098029/"
}

Send latitude and longitude together; without them Yandex answers from its own default region. span is half the width of the search box in degrees, and bounds=restrict drops businesses outside it. language takes en_US, ru_RU, tr_TR or uk_UA and sets the language of names, addresses and working_time_text, Yandex's one-line summary of the week's hours. The response has no reliable total: total_result_count_estimate grows as you page. Walk pages until one brings no new id.

Export Yandex Maps businesses to CSV

The script takes a query, a latitude and a longitude, and walks pages of 25 until a page adds no business it has already seen. Yandex adds ad-tracking parameters to many website links, so the script keeps each link up to the ?. It also rounds rating.value to one decimal. The fourth argument caps the pages, 10 by default; the run below sets 60.

python
import csv
import os
import sys
import time

import requests

API = "https://api.toolzerhub.com/v1/yandex/maps/search"
KEY = os.environ.get("TOOLZERHUB_API_KEY")
FIELDS = ["name", "category", "address", "phones", "websites", "social", "rating", "ratings", "reviews",
          "hours", "latitude", "longitude", "url"]


def cell(value):
    # A leading = + - or @ would run as a formula when the CSV opens in a spreadsheet.
    return "'" + value if isinstance(value, str) and value[:1] in ("=", "+", "-", "@") else value


def get(params, tries=4):
    # 429 and 503 are worth a retry; the body says how long to wait.
    for attempt in range(tries):
        r = requests.get(API, params=params, headers={"x-api-key": KEY}, timeout=90)
        if r.status_code in (429, 503) and attempt < tries - 1:
            wait = int(((r.json().get("error") or {}).get("details") or {}).get("retryAfter") or r.headers.get("Retry-After") or 5 * (attempt + 1))
            time.sleep(min(wait, 60))
            continue
        r.raise_for_status()
        return r.json()["data"]


def row(place):
    rating = place.get("rating") or {}
    return {
        "name": place["title"],
        "category": ((place.get("categories") or [{}])[0]).get("name"),
        "address": place.get("full_address") or place.get("address"),
        "phones": "; ".join(p["number"] for p in place.get("phones") or []),
        # Yandex adds ad-tracking parameters to many links; keep the address before the "?".
        "websites": "; ".join(w.split("?")[0] for w in place.get("websites") or []),
        "social": "; ".join(s["href"] for s in place.get("social_links") or []),
        "rating": rating.get("value") and round(rating["value"], 1),
        "ratings": rating.get("ratings"),
        "reviews": rating.get("reviews"),
        "hours": place.get("working_time_text"),
        "latitude": place.get("latitude"),
        "longitude": place.get("longitude"),
        "url": place.get("url"),
    }


def main(query, latitude, longitude, max_pages="10", out="yandex.csv"):
    seen, rows, calls = set(), [], 0
    for page in range(int(max_pages)):
        data = get({"query": query, "latitude": latitude, "longitude": longitude, "span": 0.1,
                    "language": "ru_RU", "results": 25, "page": page})
        calls += 1
        # Deeper pages repeat earlier rows; stop when a page brings nothing new.
        new = [p for p in data["results"] if p["type"] == "business" and p["id"] not in seen]
        if not new:
            break
        seen.update(p["id"] for p in new)
        rows += [row(p) for p in new]
    with open(out, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        writer.writeheader()
        writer.writerows({k: cell(v) for k, v in r.items()} for r in rows)
    print(f"{len(rows)} businesses in {calls} calls, saved to {out}")


if __name__ == "__main__":
    if not KEY or len(sys.argv) < 4:
        sys.exit("usage: TOOLZERHUB_API_KEY=... python yandex_businesses.py QUERY LATITUDE LONGITUDE [max_pages] [file.csv]")
    main(*sys.argv[1:])

What came out

python yandex_businesses.py стоматология 59.9343 30.3351 60 spb-dentists.csv saved 503 businesses in 24 calls and 97 seconds. The 24th page brought no new clinic, so the walk stopped there.

  • 495 had a phone, 393 a website and 363 at least one social link; 6 had neither a phone nor a website. One clinic listed six phones.
  • All 503 addresses were in St Petersburg. Most were dental clinics (453), with 22 medical centres and 16 dental polyclinics. Six were open around the clock.
  • 267 clinics linked to VK, 226 to Telegram, 193 to WhatsApp, 97 to the Max messenger and 69 to YouTube.
  • All 503 were rated, at an average of 4.56, with 69,503 reviews between them: 61 for the median clinic and 2,275 for the busiest.
  • Most phone numbers start with +, so the formula guard writes them with a leading apostrophe. Drop it before you load the CSV into a database.

What it costs

A call returns up to 25 businesses for 1 credit, so the 503 clinics cost 24 credits. The 100 free credits a month cover about 2,000 businesses; $19 buys 10,000 credits that never expire, and plans for higher volume cover more cities. Set your key and your first city is a CSV in under two minutes.

The same job on 2GIS is the 2GIS parser in Python, and for reviews of the clinics you found, see the Yandex Maps reviews API guide.

We are not affiliated with Yandex.

Get this data from your own code

The Yandex API returns it as JSON with one x-api-key header. 100 free credits monthly.