2GIS API2gis.ru ↗
Search companies and retrieve full business profiles from 2GIS across Russian cities. Returns contacts, working hours, ratings, categories, and addresses.
What is the 2GIS API?
The 2GIS API gives developers access to the 2GIS Russian business directory through 2 endpoints. Use search_companies to query businesses by name, category, or keyword within a specific city, and get_company_profile to pull a full record — including phones, email, website, working hours, description, and rating — for any company by its 2GIS ID.
curl -X GET 'https://api.parse.bot/scraper/c52211d8-4777-48ae-b146-478d77dace4f/search_companies?city=%D0%9D%D0%BE%D0%B2%D0%BE%D1%81%D0%B8%D0%B1%D0%B8%D1%80%D1%81%D0%BA&page=1&query=%D0%BA%D0%BE%D1%84%D0%B5%D0%B9%D0%BD%D1%8F' \ -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 2gis-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.
"""Walkthrough: 2GIS SDK — bounded, re-runnable; every call capped."""
from parse_apis.api_2gis_ru_api import TwoGis, NotFound
client = TwoGis()
# Search for coffee shops in Novosibirsk, limited to 3 results.
for company in client.companies.search(query="кофейня", city="Новосибирск", limit=3):
print(company.name, company.address, company.rating)
# Drill-down: take one result and get full details.
hit = client.companies.search(query="аптека", city="Москва", limit=1).first()
if hit:
try:
full = hit.details()
print(full.name, full.address, full.working_hours)
except NotFound as e:
print("not found:", e)
print("exercised: companies.search, CompanySummary.details")
Search for companies by name or category in a given city. Returns paginated results with basic company info including name, address, contact details, category, and rating. Results are ordered by relevance within the specified city.
| Param | Type | Description |
|---|---|---|
| cityrequired | string | City name in Russian (e.g. 'Новосибирск', 'Москва'). |
| page | integer | Page number for paginated results. |
| queryrequired | string | Search query — company name, category, or keyword (e.g. 'кофейня', 'аптека'). |
{
"type": "object",
"fields": {
"page": "current page number",
"items": "array of company summaries",
"total": "total number of matching companies"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"id": "70000001059067661",
"name": "Куликовский, кофейня-кондитерская",
"email": "[email protected]",
"phones": [
"+1 (555) 012-3456",
"+1 (555) 012-3457"
],
"rating": 4.5,
"address": "улица Кирова, 48",
"website": "kulikov.com",
"category": "Кофейни"
}
],
"total": 376
},
"status": "success"
}
}About the 2GIS API
Searching the Directory
The search_companies endpoint accepts a query parameter (company name, category keyword like кофейня or аптека) and a required city parameter in Russian (e.g. Москва, Новосибирск). Results are ordered by relevance within that city. The response includes a total count, the current page number, and an items array of company summaries covering name, address, contact details, primary category, and rating. Use the page parameter to walk through paginated results.
Company Profiles
Once you have a company ID from search_companies, pass it to get_company_profile to retrieve the full record. The response exposes 10 fields: id, name, address, phones (array), email, website, category, rating (1–5 scale or null), description, and working_hours. The working_hours field is an object keyed by day abbreviations, each mapping to an array of time ranges — useful for building hours-aware search tools or validating whether a business is currently open.
Coverage and Scope
2GIS is a Russian-market directory with strong coverage of businesses across major Russian cities. City names must be provided in Russian for the search to resolve correctly. Rating values follow a 1–5 scale and may be null if a business has no reviews. Fields like email, website, and description are nullable and may be absent for many smaller or less-active listings.
The 2GIS API is a managed, monitored endpoint for 2gis.ru — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 2gis.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 2gis.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 city-specific business finder filtered by category keyword (e.g.
аптека,ресторан) usingsearch_companies. - Aggregate contact data — phones, email, website — for businesses in a target Russian city for B2B prospecting.
- Enrich a CRM with verified addresses, categories, and working hours by resolving known business names to 2GIS profiles.
- Monitor business rating changes over time by periodically fetching
get_company_profilefor a watchlist of company IDs. - Build an hours-aware store locator that reads the
working_hoursobject to show currently open businesses. - Map competitor density across Russian cities by searching category keywords and counting
totalresults per city.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does 2GIS have an official developer API?+
What does `get_company_profile` return that `search_companies` does not?+
search_companies returns summary fields sufficient for listing results. get_company_profile adds phones (full array), email, website, description, and working_hours — the structured hours object keyed by day abbreviations. These fields are not present in the search results items array.Are there limitations on which cities or regions are covered?+
city parameter must be provided in Russian (Cyrillic). Cities outside 2GIS's covered regions will return empty or low-quality results. There is no built-in way to enumerate all available cities through the current endpoints.Does the API return user reviews or review text?+
rating (a 1–5 numeric value or null) but does not return individual reviews, review counts, or review text. You can fork this API on Parse and revise it to add a reviews endpoint if that data is needed.Can I retrieve a list of all businesses in a category without a specific search query?+
query parameter on search_companies is required, so you must supply at least a category keyword or name. Broad category terms like кафе or магазин work as queries and will return paginated results across the city. There is no browse-all or category-tree endpoint currently. You can fork the API on Parse and revise it to add a category listing endpoint.