2GIS API2gis.ae ↗
Access UAE business listings, contacts, reviews, photos, menus, and categories from 2GIS.ae via 11 structured REST endpoints.
What is the 2GIS API?
The 2GIS UAE API provides access to 11 endpoints covering the full 2GIS.ae business directory for the UAE, returning structured data on company profiles, contacts, reviews, photos, menus, and geographic categories. The search_companies endpoint accepts keyword queries with optional filters like {"work_time": "now"} and returns paginated results including addresses, schedules, ratings, and contact summaries. Organization-level data can be expanded to individual branches using get_company_branches.
curl -X GET 'https://api.parse.bot/scraper/a33a4849-01d7-4cc2-925b-ba10d63e461b/search_companies?page=1&limit=5&query=restaurants' \ -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-ae-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 UAE business directory — bounded, re-runnable."""
from parse_apis._2GIS_UAE_API import TwoGis, CompanyNotFound
client = TwoGis()
# Search for restaurants — limit caps total items fetched.
for company in client.company_summaries.search(query="restaurants", limit=3):
print(company.name, company.address_name)
# Drill into the first result for full details.
first = client.company_summaries.search(query="hotels dubai", limit=1).first()
if first:
detail = first.details()
print(detail.name, detail.timezone_offset)
# Sub-resources: reviews for this company.
for review in first.reviews.list(limit=2):
print(review.text, review.rating, review.date_created)
# Sub-resources: photos for this company.
for photo in first.photos.list(limit=2):
print(photo.id, photo.media_type)
# Browse top-level categories.
for cat in client.categories.browse(limit=5):
print(cat.name, cat.tag)
# Typed error handling on a details call.
bad = client.company_summaries.search(query="zzzzzzz_nonexistent", limit=1).first()
if bad:
try:
detail = bad.details()
print(detail.name)
except CompanyNotFound as exc:
print(f"Company not found: {exc.company_id}")
print("exercised: search / details / reviews.list / photos.list / categories.browse")
Full-text search over UAE business listings. Matches company name, category, and address against the query. Returns paginated results with address, contact info, reviews summary, schedule, and location. Paginates via integer page number. Each result carries enough detail for a listing card; drill into get_company_details for the full profile.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| limit | integer | Number of results per page. |
| query | string | Search keyword (e.g. 'restaurants', 'hotels dubai'). |
| filters | string | JSON string of additional filters (e.g. '{"work_time": "now"}'). |
{
"type": "object",
"fields": {
"page": "integer current page number",
"items": "array of company summary objects with id, name, address, point, reviews, rubrics, schedule, contacts",
"total": "integer total number of matching results"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"id": "70000001019627575",
"name": "Najmat Lahore, restaurant",
"type": "branch",
"point": {
"lat": 25.355036,
"lon": 55.382158
},
"reviews": {
"general_rating": 4.2,
"general_review_count": 19
},
"rubrics": [
{
"id": "161",
"name": "Cafe / Restaurants"
}
],
"address_name": "Al Saud Building, 50, Al Marija street"
}
],
"total": 24207
},
"status": "success"
}
}About the 2GIS API
Search and Company Data
The search_companies endpoint accepts a query string (e.g. 'hotels dubai') plus optional filters as a JSON string, page, and limit for pagination. Results come back as a result.items array of company summaries including address, contact info, review rating, opening schedule, and geographic coordinates. To retrieve the full profile for a specific listing, pass its ID to get_company_details, which returns attributes, photos availability flags, rating breakdowns, and the org.id needed for branch lookups.
Contacts, Reviews, and Media
get_company_contacts returns structured contact groups with typed entries for phone numbers, email addresses, websites, and social media handles — all keyed to a company_id. Reviews are available through get_company_reviews, which returns an array of objects containing id, rating, text, user info, and timestamps. Pagination uses a cursor pattern: pass the date_created value of the last review as offset_date to fetch the next page, and follow the meta.next_link field.
Photos are split between two endpoints. get_company_photos returns all company images with photo URLs, media_type, album metadata (id, name, count), and a pagination token. get_company_menu scopes the same photo structure to the price_list_image album specifically, making it straightforward to retrieve menu or price-list images separately from general photos.
Categories and Discovery
browse_categories returns the 2GIS category tree. Without a parent_id it returns top-level metarubric entries with icons and tags; supply a parent_id to drill into subcategories. Once you have a rubric ID, search_by_category lists all companies in that category with the same paginated structure as search_companies. get_featured_places returns curated popular categories for the UAE region with no required inputs. list_cities returns all available regions on 2GIS with their IDs and names, useful for scoping subsequent queries.
The 2GIS API is a managed, monitored endpoint for 2gis.ae — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 2gis.ae 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.ae 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 UAE restaurant finder that queries
search_by_categorywith the Cafe/Restaurants rubric ID and displays menus fromget_company_menu. - Aggregate contact details for UAE businesses in a specific industry by combining
search_companiesresults withget_company_contacts. - Monitor business reputation by collecting review text, ratings, and dates from
get_company_reviewsacross multiple company IDs. - Map all branches of a UAE retail chain by fetching branch addresses and coordinates via
get_company_branchesusing the organization'sorg.id. - Populate a local business directory with structured opening hours, phone numbers, and photos pulled from
get_company_detailsandget_company_photos. - Discover high-traffic business categories in the UAE using
get_featured_placesand drill into listings withsearch_by_category. - Filter businesses currently open by passing
{"work_time": "now"}in thefiltersparameter ofsearch_companies.
| 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 2GIS offer an official developer API?+
How does pagination work for reviews in `get_company_reviews`?+
meta.next_link field. To fetch the next page, pass the date_created value of the last review on the current page as the offset_date parameter in your next request. This approach handles cases where new reviews are added between requests more reliably than offset pagination.Does the API return geocoordinates or routing data for companies?+
search_companies and branch records from get_company_branches include location data. The API does not currently expose turn-by-turn routing, distance-matrix calculations, or isochrone data. You can fork this API on Parse and revise it to add a routing or geocoding endpoint if that coverage is needed.Are there limitations on geographic coverage — does this cover all UAE cities?+
list_cities returns all regions indexed on 2GIS for the UAE. Coverage depth varies by city; major cities like Dubai, Abu Dhabi, and Sharjah have dense listings while smaller emirates may have fewer entries. The API does not cover 2GIS data outside the UAE (e.g. Russia, Kazakhstan, or other markets where 2GIS operates). You can fork it on Parse and revise it to target a different regional 2GIS domain if needed.Can I retrieve individual review responses from business owners?+
get_company_reviews endpoint returns review objects with user-submitted text, ratings, and timestamps. Owner replies to reviews are not currently included in the response. You can fork this API on Parse and revise it to add owner-response fields if your use case requires them.