# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/openrice/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/openrice/get-award-winners \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/get-booking-info \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/get-new-restaurants \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/get-restaurant-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/get-restaurant-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/list-cuisines \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/list-districts \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/openrice/search-restaurants \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"cuisine_id":"<string>","district_id":"<string>","query":"<string>","rows":"<integer>","sort_by":"<string>","start_at":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.