# 2GIS API — business search, business card, reviews, categories and cities from 2GIS (2gis.ru, 2gis.kz, 2gis.ae …) across Russia, Kazakhstan, Central Asia, the Caucasus and the Gulf: name, rubrics, address, coordinates, phones, emails, websites and social links as published, opening hours, rating, review count and paginated customer reviews

> Search 2GIS businesses by text and/or rubric in a city, or around a point. Up to 50 rows per page with phones, emails, websites, social links, hours, rating and review count; filters for photos, website and open-at time; sort by relevance, rating, name or distance. Either query or rubric_id is required.
> ReefAPI engine `2gis` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/2gis/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 calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/2gis/v1/search — 2 credits
Search 2GIS businesses by text and/or rubric in a city, or around a point. Up to 50 rows per page with phones, emails, websites, social links, hours, rating and review count; filters for photos, website and open-at time; sort by relevance, rating, name or distance. Either query or rubric_id is required.

**Parameters:**
- `query` (string, optional) — What to look for: a business name, brand or category in any language 2GIS indexes ('кофейня', 'стоматология', 'Starbucks', 'coffee'). Either query or rubric_id is required.
- `rubric_id` (string, optional) — Only businesses in this 2GIS rubric (category) id — from the `rubrics` action or a row's rubrics[].id (162 = coffee shops in Russia). Works with or without query.
- `city` (string, optional) — 2GIS region: its code (moscow, spb, novosibirsk, almaty, astana, tashkent, dubai, riyadh …), its numeric region_id, or its Russian name ('Москва'). The `cities` action lists all 207. Default moscow when neither city nor ll is given (meta.region_defaulted=true).
- `ll` (string, optional) — Search around a point, 'lon,lat' (longitude FIRST). With radius it limits results to that circle; with sort=distance it orders nearest first.
- `radius` (integer, optional) — Radius in metres around ll (1-40000). Requires ll.
- `sort` (enum, optional, default "relevance") — Result order. distance needs ll. [one of: relevance, rating, name, distance]
- `has_photos` (boolean, optional) — Only businesses with photos (кофе Moscow: 18,426 → 9,660).
- `has_website` (boolean, optional) — Only businesses with a website (кофе Moscow: 18,426 → 5,207).
- `open_at` (string, optional) — Only businesses open at this weekday and local time, '<day>,<HH:MM>' with day mon..sun (кофе Moscow mon,23:30: 18,426 → 775).
- `page` (integer, optional, default 1) — Result page. meta.total / meta.total_pages say how far it goes; past the last page the answer is empty with meta.page_out_of_range=true.
- `page_size` (integer, optional, default 12) — Rows per page, 1-50 (2GIS's own site shows 12).
- `locale` (string, optional) — Language of names and rubric labels, e.g. ru_RU, en_AE, ar_AE, ru_KZ, kk_KZ, uz_UZ. Default: the region's own locale.

**Returns:** rows[]{org_id, name, name_primary, name_extension, brand_id, brand_name, brand_branch_count, address, full_address, address_comment, street, house, postcode, country, region, city, district, latitude, longitude, rubrics[], phones[]{number, display, comment}, emails[], websites[], social_links[]{type, url, handle}, other_contacts[], hours{mon..sun: ['HH:MM-HH:MM']}, is_24x7, hours_comment, rating, review_count, rating_count, brand_rating, brand_review_count, photo_count, main_photo_url, is_advertiser, updated_at, url} + meta{total, page, total_pages, has_more, region}

**Example request body:**
```json
{
  "query": "кофейня",
  "city": "moscow"
}
```

### POST https://api.reefapi.com/2gis/v1/detail — 2 credits
Full 2GIS business card by org_id (or firm url): everything a search row has plus the attribute list (average bill, cuisine, payment, amenities …), description, nearest metro stations and purpose.

**Parameters:**
- `org_id` (string, optional) — 2GIS branch id — a search row's org_id, the number in 2gis.ru/<city>/firm/<id>.
- `url` (string, optional) — Alternatively a 2GIS business address (…/firm/<id>).
- `locale` (string, optional) — Language of names and rubric labels, e.g. ru_RU, en_AE, ar_AE, ru_KZ, kk_KZ, uz_UZ. Default: the region's own locale.

**Returns:** org{… search row fields …, attributes[]{group, name, tag}, description, nearest_metro[]{station_id, distance_m}, purpose}

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

### POST https://api.reefapi.com/2gis/v1/reviews — 2 credits
Public customer reviews of one 2GIS business, newest first, up to 50 per page with cursor paging: star rating, text, dates, author name and review count, likes, photos and the business's reply.

**Parameters:**
- `org_id` (string, required) — 2GIS branch id (search row org_id).
- `limit` (integer, optional, default 50) — Reviews per page, 1-50.
- `cursor` (string, optional) — meta.next_cursor from the previous page; empty for the first page.
- `sort` (enum, optional, default "newest") — Review order. [one of: newest, edited]

**Returns:** reviews[]{review_id, rating, text, date_created, date_edited, author_name, author_id, author_reviews_count, author_photo, likes_count, comments_count, is_verified, provider, photos[], business_reply, business_reply_date, org_id} + meta{branch_rating, review_count, next_cursor, has_more}

**Example request body:**
```json
{
  "org_id": "70000001113359188",
  "limit": 20
}
```

### POST https://api.reefapi.com/2gis/v1/rubrics — 1 credit
2GIS rubric (category) tree for a region: the 28-or-so top groups, or the rubrics under one group (parent_id), with how many branches and organisations each holds there.

**Parameters:**
- `city` (string, optional) — Region code, id or Russian name (default moscow).
- `parent_id` (string, optional) — A top-group rubric_id to list its rubrics; empty = top groups.
- `locale` (string, optional) — Language of names and rubric labels, e.g. ru_RU, en_AE, ar_AE, ru_KZ, kk_KZ, uz_UZ. Default: the region's own locale.

**Returns:** rubrics[]{rubric_id, name, alias, type, parent_id, branch_count, org_count}

**Example request body:**
```json
{
  "city": "almaty"
}
```

### POST https://api.reefapi.com/2gis/v1/cities — 2 credits
Every region 2GIS covers (207 on 2026-11-03): region id, code, name, country, locale, time zone and centre point — the values `city` accepts.

**Parameters:**
- `country` (string, optional) — Only regions of this ISO country code (ru, kz, uz, kg, ae, sa …).
- `locale` (string, optional) — Language of region names: ru_RU (default) or en_AE, ar_AE …

**Returns:** cities[]{region_id, code, name, country_code, domain, locale, time_zone, latitude, longitude, url}

**Example request body:**
```json
{
  "country": "kz"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

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