OpenTable Restaurant Search API
Find restaurants near a location for a given date, time, and party size.
Overview
Restaurant list, not time slots
This endpoint returns the matching restaurant list with rich metadata. Bookable reservation time slots are not included on this surface — availability is planned as a separate endpoint.
The OpenTable Search endpoint discovers restaurants around a latitude/longitude for a specific reservation date, time, and party size. It is backed by the same front-end GraphQL gateway that www.opentable.com uses, and returns up to 50 restaurants per call with cuisine, price band, guest rating, photos, structured address, phone, and feature flags (takeout, private dining, online ordering).
Endpoint URL
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| latitude | float | Required | Search-center latitude (-90 to 90). |
| longitude | float | Required | Search-center longitude (-180 to 180). |
| date | string | Required | Reservation date in YYYY-MM-DD. Cannot be in the past. |
| time | string | Required | Reservation time in HH:MM (24-hour), e.g. 19:00. |
| party_size | integer | Optional | Number of diners (1-30). Default: 2 |
| prices | integer[] | Optional | Price-band filter (1=$ … 4=$$$$). Repeatable — e.g. prices=2&prices=3. |
| metro_id | integer | Optional | OpenTable metro id; narrows the search to a metro area. |
| limit | integer | Optional | Maximum restaurants to return (1-50). Default: 50 |
| offset | integer | Optional | Pagination offset (≥ 0). Default: 0 |
Search needs coordinates
OpenTable search is coordinate-based — there is no city-name search. Resolve a place name to latitude/longitude first, for example with the Meta Coordinates Lookup endpoint (GET /v1/meta/coordinates-lookup).
Response Format
The response returns the list of matching restaurants for the search, each with cuisine, price band, rating, photos, address, phone, and feature flags.
Response Structure
- success: Boolean indicating request success
- total: OpenTable's total match count for the search (may exceed the number returned)
- restaurants: Array of restaurant objects
Restaurant Object Fields
| Field | Type | Description |
|---|---|---|
| id | integer | OpenTable restaurant id. Stable. |
| name | string | Restaurant name |
| url | string | OpenTable restaurant page URL |
| primary_cuisine | string | Primary cuisine, e.g. "French American" |
| dining_style | string | Dining style, e.g. "Casual Elegant" |
| price_band | object | Price band: id (1-4, maps to the prices filter), name (e.g. "$31 to $50"), currency_symbol |
| rating | float | Guest-review score (0-5). May be null for newly listed restaurants. |
| review_count | integer | All-time text-review count. May be null. |
| recent_reservation_count | integer | Recent reservations booked through OpenTable |
| neighborhood | string | Neighborhood name |
| coordinates | object | Restaurant latitude / longitude |
| address | object | Structured address: line1, line2, city, state, postal_code |
| phone | string | Restaurant phone number |
| photos | array | Ready-to-use CDN photo URLs |
| description | string | Plain-text restaurant description |
| max_party_size | integer | Largest party the restaurant accepts online |
| has_takeout | boolean | Whether takeout is offered |
| order_online_link | string | Online-ordering link (may be null) |
| has_private_dining | boolean | Whether the restaurant offers private dining (see the Private Dining endpoint) |
total vs. returned count
total is OpenTable's full match count for the search and can exceed the number of restaurants returned (capped by limit, max 50). Page through additional matches with offset.
Error Responses
The API returns standard HTTP error codes with detailed messages following the RFC 7807 Problem Details format. Failures carry provider: "opentable" and product: "search".
400 Bad Request
An input failed validation. Possible error_code values: INVALID_DATE_FORMAT (date not YYYY-MM-DD), PAST_DATE (date before today), INVALID_TIME_FORMAT (time not HH:MM), INVALID_PRICE_BAND (a prices value outside 1-4).
{
"type": "https://api.stayapi.com/errors/invalid-date-format",
"title": "Invalid Date Format",
"status": 400,
"detail": "date must be in YYYY-MM-DD format",
"provider": "opentable",
"product": "search",
"error_code": "INVALID_DATE_FORMAT"
}
422 Unprocessable Entity
A parameter is missing or out of range (e.g. bad coordinates, limit > 50, party_size > 30).
502 Bad Gateway
Upstream service error from OpenTable after retries (UPSTREAM_ERROR).
Usage Tips
Best Practices
- Geocode a place name to coordinates first — pair this with the Meta Coordinates Lookup endpoint
- Filter by budget with one or more
pricesvalues (1-4); repeat the param to combine bands - Use
limit+offsetto page;totaltells you how many matches exist beyond the page - Treat
ratingandreview_countas nullable — newly listed restaurants may have neither
Rate Limiting
This endpoint is subject to your plan's rate limits. Each search counts as one API call regardless of the number of results returned.
Related Endpoints
OpenTable Private Dining
Find venues that offer private dining, with contact and capacity details
View Documentation →Meta Coordinates Lookup
Resolve a place name into latitude/longitude for the search
View Documentation →