# 2GIS UAE — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and explore businesses across the UAE with access to comprehensive company profiles, contact information, reviews, photos, and menus all in one place. Browse categories, find branch locations, discover featured places, and get detailed insights about any business to make informed decisions.

**Category:** Business Directories | **Website:** [2gis.ae/](https://2gis.ae/) | **Docs:** [parse.bot/marketplace/e87f1549-eb8a-4447-b08d-a40b231a9485/2gis-ae-api](https://parse.bot/marketplace/e87f1549-eb8a-4447-b08d-a40b231a9485/2gis-ae-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### browse_categories

Browse top-level business categories (metarubrics) or subcategories of a parent. Returns category entries with icons, tags, and IDs usable with search_by_category. When parent_id is omitted, returns the top-level categories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `parent_id` | string | No | Parent category ID to fetch subcategories for. If omitted, returns top-level categories. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/browse_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent_id":"<string>"}'
```

### get_company_branches

Get all branches of a specific organization. Returns branch addresses, names, schedules, and location coordinates. The org_id comes from a company detail's org.id field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `org_id` | string | Yes | The organization ID (from company details org.id field). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_company_branches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<string>"}'
```

### get_company_contacts

Extract contact information (phone numbers, email, website, social media links) for a company. Returns structured contact groups with type and value for each entry.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_id` | string | Yes | The unique branch ID of the company. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_company_contacts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id":"<string>"}'
```

### get_company_details

Retrieve the full profile of a single company by its branch ID. Includes address, contacts, schedule, rating, attribute groups (cuisine type, amenities), photo flag, organization info, and location coordinates. The ID comes from search_companies or search_by_category results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_id` | string | Yes | The unique branch ID of the company (from search results items[*].id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_company_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id":"<string>"}'
```

### get_company_menu

Retrieve menu/price list images for a company. Returns photos from the price_list_image album. Not all companies have menu images — an empty items array is a valid response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_id` | string | Yes | The unique branch ID of the company. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_company_menu \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id":"<string>"}'
```

### get_company_photos

Retrieve photos associated with a company. Returns photo URLs with dimensions and album breakdown. Photos are from the 'all' album by default.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_id` | string | Yes | The unique branch ID of the company. |
| `limit` | integer | No | Max photos to return. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_company_photos \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id":"<string>","limit":"<integer>"}'
```

### get_company_reviews

Fetch user reviews for a company, ordered by date created (newest first). Supports cursor-based pagination via offset_date — pass the date_created of the last review from the previous page to get the next batch. Each review includes rating, text, user info, and timestamps.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `company_id` | string | Yes | The unique branch ID of the company. |
| `limit` | integer | No | Max reviews to return per page. |
| `offset_date` | string | No | For pagination: the date_created value of the last review from the previous page (ISO 8601 format, e.g. '2025-05-17T09:43:40.323516+07:00'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_company_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id":"<string>","limit":"<integer>","offset_date":"<string>"}'
```

### get_featured_places

Get featured or popular categories/places in the UAE region. Returns metarubric entries commonly used by visitors (e.g. Eat out, Groceries, ATMs, Pharmacies).

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/get_featured_places \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_cities

Retrieve all available countries and regions on 2GIS. Returns a list of regions with their IDs, names, and types. Useful for discovering which regions are supported.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/list_cities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_by_category

List all companies in a specific category (rubric). Returns paginated results with the same shape as search_companies. Use rubric IDs from browse_categories subcategory results (e.g. '161' for Cafe/Restaurants).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Page number for pagination. |
| `rubric_id` | string | Yes | The rubric ID (e.g. '161' for Cafe/Restaurants, from browse_categories results). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/search_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","rubric_id":"<string>"}'
```

### search_companies

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filters` | string | No | JSON string of additional filters (e.g. '{"work_time": "now"}'). |
| `limit` | integer | No | Number of results per page. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search keyword (e.g. 'restaurants', 'hotels dubai'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-2gis-ae-api-e87f1549/search_companies \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":"<string>","limit":"<integer>","page":"<integer>","query":"<string>"}'
```