Yandex APIyandex.ru ↗
Search Yandex Maps businesses by city and query. Returns names, addresses, phones, websites, hours, categories, ratings, and coordinates via 2 endpoints.
What is the Yandex API?
The Yandex Maps Business API exposes 2 endpoints for finding and retrieving Russian and CIS business listings. search_companies accepts a query term plus city or region ID and returns up to 25 companies per page with phones, websites, categories, and ratings. get_company_details returns full structured data for a single organization by its Yandex Maps ID, including coordinates, all associated URLs, and social links.
curl -X GET 'https://api.parse.bot/scraper/287a70d8-be62-4a52-9e5b-49e263391bac/search_companies?city=moscow&page=1&query=%D0%BA%D0%BE%D1%84%D0%B5®ion_id=213' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace yandex-ru-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.yandex_maps_business_search_api import YandexMaps, Company, CompanyNotFound
client = YandexMaps()
# Search for coffee shops in Moscow
for company in client.companies.search(query="кофе", city="moscow", region_id="213", limit=5):
print(company.name, company.address, company.working_hours)
if company.rating:
print(company.rating.score, company.rating.reviews_count)
for phone in company.phones:
print(phone.number, phone.value)
# Get detailed info about a specific company
details = client.companies.get(company_id="232950636517")
print(details.name, details.address, details.website)
for link in details.social_links:
print(link.type, link.url, link.display)
for cat in details.categories:
print(cat.id, cat.name)
Search for companies/businesses on Yandex Maps by query term in a specific city. Returns a paginated list of companies with full contact details including phones, websites, social links, working hours, categories, and ratings. Each page returns up to 25 results. Pagination via page parameter; total_results indicates the full count available.
| Param | Type | Description |
|---|---|---|
| city | string | City name in URL slug format (e.g. 'moscow', 'saint_petersburg'). |
| page | integer | Page number for pagination. Each page returns up to 25 results. |
| query | string | Search query in any language (e.g. 'кофе', 'restaurants', 'graphic design'). |
| region_id | string | Yandex region ID as a numeric string (213 for Moscow, 2 for Saint Petersburg). |
{
"type": "object",
"fields": {
"city": "string, the city searched",
"page": "integer, the current page number",
"query": "string, the search query used",
"companies": "array of Company objects",
"total_results": "integer, total number of matching results",
"results_per_page": "integer, max results per page (typically 25)",
"companies_on_page": "integer, actual number of companies returned on this page"
},
"sample": {
"data": {
"city": "moscow",
"page": 1,
"query": "кофе",
"companies": [
{
"id": "60041962835",
"name": "Bash Coffee",
"phones": [
{
"type": "phone",
"value": "+15550123456",
"number": "+1 (555) 012-3456"
}
],
"rating": {
"score": null,
"reviews_count": 61
},
"address": "Moscow, Vorontsovo Pole Street, 18",
"website": "https://bash-coffee.clients.site/",
"all_urls": [
"https://bash-coffee.clients.site/"
],
"categories": [
{
"id": "35193114937",
"name": "Coffee shop"
}
],
"coordinates": [
37.65569,
55.754569
],
"description": "Vorontsovo Pole Street, 18",
"social_links": [],
"working_hours": "Mon-Fri 8:00 AM–10:00 PM; Sat,Sun 9:00 AM–9:00 PM"
}
],
"total_results": 106,
"results_per_page": 25,
"companies_on_page": 24
},
"status": "success"
}
}About the Yandex API
Searching for Businesses
The search_companies endpoint accepts a query (any language — Russian or English both work), a city slug such as moscow or saint_petersburg, and optionally a region_id numeric string (e.g. 213 for Moscow, 2 for Saint Petersburg). Results are paginated; each page holds up to 25 companies, and the response includes total_results so you can calculate how many pages exist. Each company object in the companies array contains name, address, phone array, website, categories, and rating.
Company Detail Records
get_company_details takes a company_id obtained from search_companies results and returns a richer record for that single organization. The response adds coordinates as a [longitude, latitude] pair, an all_urls array listing every URL associated with the business (useful for catching social profiles not surfaced in website), a description string, and a structured rating object with score and reviews_count. The categories field is an array of objects each carrying both an id and a human-readable name.
Coverage and Pagination
The API covers businesses listed on Yandex Maps, which has dense coverage across Russia, Ukraine, Belarus, Kazakhstan, and other CIS territories. Queries in Cyrillic or Latin script both resolve correctly. Pagination is controlled by the page integer parameter; the response echoes back page, results_per_page, and companies_on_page so you can detect the last page when companies_on_page is less than results_per_page.
The Yandex API is a managed, monitored endpoint for yandex.ru — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when yandex.ru changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official yandex.ru API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a local business directory for a Russian city using names, addresses, and phone numbers from
search_companies. - Geocode business locations by pulling
coordinatesfromget_company_detailsfor mapping or spatial analysis. - Aggregate competitor listings in a specific category by querying category keywords across multiple pages.
- Verify or enrich a CRM with current phone numbers and websites for Russian SMEs.
- Collect all URLs associated with a business via
all_urlsto discover social media profiles and secondary sites. - Monitor rating scores and review counts for businesses in a target city over time.
- Compile working hours data from company records to build a real-time open/closed indicator for a local services app.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Yandex have an official developer API for Maps business data?+
What does `get_company_details` return that `search_companies` does not?+
get_company_details adds coordinates ([longitude, latitude]), a description string, an all_urls array covering every URL tied to the organization, and a fully structured rating object with both score and reviews_count. The search endpoint surfaces a subset of these fields per company to keep page payloads manageable.Can I filter `search_companies` results by category or rating?+
query, city, region_id, and page as inputs. Filtering by category ID or minimum rating is not a built-in parameter — you would apply those filters client-side after receiving results. You can fork this API on Parse and revise the endpoint to add server-side category or rating filters if needed.Does the API cover businesses outside Russia and CIS countries?+
region_id and city parameters tied to Yandex's region taxonomy, which is centered on Russian-speaking geographies. You can fork the API on Parse and revise it to target other Yandex region IDs if partial coverage in other countries is sufficient for your use case.How should I handle pagination to retrieve all results for a query?+
page: 1 and check total_results divided by results_per_page (25) to determine the page count. On the final page, companies_on_page will be less than 25. Increment page until companies_on_page equals zero or all pages are consumed. Note that Yandex Maps caps deep pagination, so very large result sets may not be fully traversable beyond a certain page depth.