# Openrice — 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 for restaurants across Hong Kong and discover detailed information including reviews, cuisines, districts, and award-winning establishments. Browse new restaurant openings and filter by location or cuisine type to find exactly what you're looking for.

**Category:** Food & Dining | **Website:** [openrice.com/](https://openrice.com/) | **Docs:** [parse.bot/marketplace/6f3503d9-309f-4a9a-8b24-58a8a1ee7a1e/openrice-com-api](https://parse.bot/marketplace/6f3503d9-309f-4a9a-8b24-58a8a1ee7a1e/openrice-com-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-openrice-com-api-6f3503d9/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_award_winners

Get OpenRice Best Restaurant Award winners. Offset-based pagination via start_at.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rows` | integer | No | Number of results to return per page |
| `start_at` | integer | No | Offset for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/get_award_winners \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":"<integer>","start_at":"<integer>"}'
```

### get_booking_info

Get booking availability information for a specific restaurant, including available time slots, offers, and seat limits. This provides read-only booking data; actual booking requires authentication on OpenRice.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | No | Booking date in YYYY-MM-DD format. Omitting returns the next available date. |
| `poi_id` | string | Yes | The restaurant's POI ID (from search_restaurants results[*].poiId) |
| `seats` | string | No | Number of seats to check availability for |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/get_booking_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>","poi_id":"<string>","seats":"<string>"}'
```

### get_new_restaurants

Get a list of newly opened restaurants in Hong Kong. Offset-based pagination via start_at.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rows` | integer | No | Number of results to return per page |
| `start_at` | integer | No | Offset for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/get_new_restaurants \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":"<integer>","start_at":"<integer>"}'
```

### get_restaurant_details

Get comprehensive details for a specific restaurant by POI ID. Returns header info (name, address, phone, scores, photos), explore services (booking widget, categories), and status (opening hours). Combines three internal calls (header, explore, status) into one response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `poi_id` | string | Yes | The restaurant's POI ID (from search_restaurants results[*].poiId) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/get_restaurant_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"poi_id":"<string>"}'
```

### get_restaurant_reviews

Fetch user reviews for a specific restaurant. Returns paginated reviews with user info, ratings, photos, and review text. Offset-based pagination via start_at.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `poi_id` | string | Yes | The restaurant's POI ID (from search_restaurants results[*].poiId) |
| `rows` | integer | No | Number of reviews to return per page |
| `start_at` | integer | No | Offset for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/get_restaurant_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"poi_id":"<string>","rows":"<integer>","start_at":"<integer>"}'
```

### list_cuisines

Get the list of cuisine types with their IDs and restaurant counts. Extracted from search filter facets. Returns all available cuisine categories for filtering in search_restaurants.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/list_cuisines \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_districts

Get the list of districts/regions in Hong Kong with their IDs for use as filters in search_restaurants. Returns a hierarchical list including parent regions and their sub-districts.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/list_districts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_restaurants

Search for restaurants in Hong Kong with various filters. Returns paginated restaurant results with search metadata and filter options. Each result includes restaurant name, address, phone numbers, pricing range, scores, photos, district, cuisine categories, and booking widget information. Offset-based pagination via start_at; each page returns up to rows results from a total pool indicated by count.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cuisine_id` | string | No | Filter by cuisine ID (use list_cuisines to get IDs) |
| `district_id` | string | No | Filter by district ID (use list_districts to get IDs) |
| `query` | string | No | Search keyword (restaurant name, food type, etc.) |
| `rows` | integer | No | Number of results to return per page |
| `sort_by` | string | No | Sort order for results |
| `start_at` | integer | No | Offset for pagination |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-openrice-com-api-6f3503d9/search_restaurants \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cuisine_id":"<string>","district_id":"<string>","query":"<string>","rows":"<integer>","sort_by":"<string>","start_at":"<integer>"}'
```