NAV
shell

Platform Basics

OpenTable uses OAuth 2.0 as the primary authorization mechanism. This means that an access token must be obtained and submitted with all requests. See Authorization section for more details.OpenTable’s Network Partner APIs can only be accessed via HTTPS. This applies to all environments.

Content Negotiation

Data is sent and received in JSON format unless otherwise specified in this documentation. Clients should specify application/json in the Accept header for all requests to the server.

Compression

OpenTable’s Partner Network APIs support LZ4 encoding. Client application should specify lz4 via the Accept-Encoding HTTP header whenever possible.

Unique Request Ids

All POST, PUT, and PATCH HTTP requests should contain a unique X-Request-Id header which is used to ensure idempotent message processing in case of a retry

Host Names

OpenTable has two primary integration environments; pre-production and production. Partners should test their integrations in pre-production where the changes are transient and do not affect live production customers or restaurants. Once partners have completed their integrations they may deploy them into the production environment. The following table lists the key hosts in each environment.

Environment Host Name
Production platform.opentable.com
Pre-production platform.otqa.com

Authorization

OpenTable uses OAuth 2.0 to authorize access to protected resources. Authorization involves following steps:

Requesting a Client Id

Self-registration for the Directory API is now available.

Obtaining an Access Token

Environment OAuth Base URL
Pre-production https://oauth-pp.opentable.com/
Production https://oauth.opentable.com/
curl --user username:password -X POST \
'https://oauth-pp.opentable.com/api/v2/oauth/token?grant_type=client_credentials'

OpenTable response :: HTTP 1.1 200 OK

json { "access_token": "a1c7b724-0a20-42be-9dd4-23d873db1f9b", "token_type": "bearer", "expires_in": 2419181, "scope": "DEFAULT" }

Clients can obtain an access token using the OAuth 2.0 client credentials flow.

URI

https://oauth.opentable.com/api/v2/oauth/token?grant_type=client_credentials

Request Parameters

Member Description
grant_type OAuth grant type. Should be “client_credentials”

Submitting Client Credentials

Client credentials are submitted in the Authorization header as defined in the OAuth spec. Given a client id (e.g., “client_id”) and a client secret (e.g., “client_secret”), you need to do the following:

  1. Concatenate them using a “:” (e.g., “client_id:client_secret”)
  2. Base64 encode the result from step 1 (e.g., “Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=”)
  3. Set the header “Authorization: Basic <result from step 2>” (e.g., “Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=”)

Authorizing Requests

Authorization: bearer a1c7b724-0a20-42be-9dd4-23d873db1f9b”)

  1. Obtain an access token
  2. Set the header “Authorization: bearer <result from step 1>” (e.g., “Authorization: bearer a1c7b724-0a20-42be-9dd4-23d873db1f9b”)
  3. Send the request a. If the token is valid and not expired, an appropriate response from the resource server will be returned. b. If the token is not valid, the resource server responds using the appropriate HTTP status code (typically, 400, 401, 403, or 405) and an error code https://tools.ietf.org/html/rfc6750#section-3.1

Token Renewal

Token expiry is included in the response. To get a new token, simply follow the process Submitting Client Credentials to obtain a new one.

Responses

OpenTable Response :: HTTP 1.1 400 Bad Request

json { "error": "invalid_request", "message": "oauth token is required to access this resource" }

OpenTable Response :: HTTP 1.1 401 Unauthorized

json { "error": "invalid_token", "message": "b7721d39-65f6-4b6a-8686-3af5246e5b3a" }

Affiliates Guide

Introduction

This section contains instructions to retrieve the directory information of all OpenTable restaurants and Implement reservation links to OpenTable.com, the OpenTable iOS app, and OpenTable Android app. This provides affiliates with the ability to easily link to restaurants that accept online reservations via OpenTable.

Retrieving Restaurant Data via Directory API

The Directory API returns a complete directory of restaurants that accept online reservations via OpenTable so that will need to first be called. The restaurant directory will be returned by the API in JSON format. The links can then be built using the data returned by the Directory API. The restaurant data is refreshed nightly, so it is recommended to call the API at least once a day to get the most current restaurant directory data.

API Access

To retrieve the data using the Directory API and linking to the reservation pages on OpenTable, the following are required:

  1. OAuth Key and Secret: Provided by OpenTable. Instructions for obtaining an access token using the key/secret pair is described in the Authorization section.
  2. ReferralID: Provided by OpenTable.

API Usage

Refer to the Directory API technical documentation for implementation details.

Linking Guidelines

Affiliates must comply with the following guidelines when using OpenTable data and linking to the OpenTable site

Linking to Individual Restaurants on OpenTable.com

The process of linking to each restaurants reservation page involves using the restaurant ID (RID) contained in the JSON response of the Directory API to build the associated reservation URLs for each restaurant, along with your unique referral ID which is by OpenTable:

http://www.opentable.com/restaurant/profile/xxxx?ref=zzzz

where “xxxx” is the restaurant’s unique OpenTable Restaurant ID as returned from the Directory API and zzzz is the numerical referral ID (this allows OpenTable to track reservations coming from your site). As an example, the link for Yamashiro for anreferral ID of 1234: http://www.opentable.com/restaurant/profile/3307?ref=1234

Country URL
North America http://www.opentable.com/restaurant/profile/xxxx?ref=zzzz
UK http://www.opentable.co.uk/restaurant/profile/xxxx?ref=zzzz
Australia http://www.opentable.com.au/restaurant/profile/xxxx?ref=zzzz
Germany http://www.opentable.de/restaurant/profile/xxxx?ref=zzzz
Japan http://www.opentable.jp/en-us/restaurant/profile/xxxx?ref=zzzz - English
Japan http://www.opentable.jp/restaurant/profile/xxxx?ref=zzzz

“Deep Linking” into the OpenTable Android App

The OpenTable Android app supports deep linking into an individual restaurant using intents. Below is an example of a deep link between the Zagat and OpenTable Android apps:

Intent structure

String deepLinkUrl = “vnd.opentable.deeplink://opentable.com/restaurant/profile?rid=xxxx?refId=zzzz?ref_id=zzzz”; Intent intent = new Intent(“android.intent.action.VIEW”); intent.setData(Uri.parse(deepLinkUrl)); startActivity(intent);

Parameter Description
rid the OpenTable Restaurant ID
refId your OpenTable referral ID
ref_id your OpenTable referral ID

“Deep Linking” into the OpenTable iOS App

The OpenTable iOS app supports deep linking using custom URL schemes into an individual restaurant profile page OR directly to the booking form.

The iOS app also supports universal links (e.g., opening desktop/mobile web links directly into the app). Universal links provide a much better experience (fall back to web if app is not installed, and convert better than web on app), and should be prefered to custom URL schemes. The only exception is when the link targets devices run iOS 8 or earlier. The app has been iOS9+ for a few months now, so there should be very limited use cases for custom URL schemes.

Custom URL schemes

Link to Restaurant or booking profile page String deep link URL = < /> “reservetable-com.contextoptional.OpenT able-1://?dt=2015-09- 25T19%3A00%3A00&rid=mmm&tsid=0&refid=zzzz&ref_id=zzzz&ps=4”

Parameter Description
rid the OpenTable Restaurant ID
refId your OpenTable referral ID
ref_id your OpenTable referral ID
dt date and time (yyyy-MM-dd’T’HH:mm:ss). Optional, if not set, the app will use its default value
ps party size. Must be bigger than 0 and smaller than 21. Optional, if not set, the app will use its default value.
tsid Setting this param opens the booking flow (omitting it, or making the param empty, opens the restaurant profile). Must be any non empty string (favor 0).

This is the preferred way of deeplinking into the iOS app. The main benefit is that these links will always work, even if the app is not installed, taking the user to safari.

Note: any URL with an sp param (paid traffic) will be sent back to safari on iOS for proper attribution; Android supports ‘sp’ URLs

Note: These Universal Links should work on Android as well, but users will see a disambiguation dialog prompting them to select the app (vs the browser).

Note: The following params should be understood on all URLs for attribution, in any casing variant. We are still asking that you be a good citizen and stick with one variant (refId or restRefId):

 refId, ref, referrerId, ref_id: for referrers

 restrefid, restref, restaurantreferralid: for rest ref IDs

Brand Assets

Affiliates must comply with the OpenTable bran guidelines when linking to the OpenTable site:

Assets Location
OpenTable Logo http://brand.opentable.com/logo#downloads
Reserve Buttons http://brand.opentable.com/partner-assets
Brand Story http://brand.opentable.com/brand-story

Directory API

The Directory API gives approved developers the ability to acquire and synchronize restaurants that are visible as search results on the OpenTable website.

Directory

curl -i -X GET \
-H 'Content-Type:application/json' \
-H 'Authorization:bearer 4b0e2253-1a34-4977-bb09-1c46a69aff50' \
'https://platform.otqa.com/sync/directory'

Use the directory entities to access restaurant details and user-facing content.

{
    "offset": 0,
    "limit": 100,
    "total_items": 35034,
    "items": [{
        "rid": 2,
        "name": "Thirsty Bear",
        "address": "661 Howard St.",
        "address2": null,
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "latitude": "37.7856500",
        "longitude": "-122.3997340",
        "postal_code": "94105",
        "phone_number": "4159740905",
        "metro_name": "San Francisco Bay Area",
        "is_restaurant_in_group": false,
        "reservation_url": "http://www.opentable.com/restaurant/profile/2",
        "profile_url": "http://www.opentable.com/restaurant/profile/2",
        "aggregate_score": "4.400",
        "price_quartile": "$$",
        "review_count": 155,
        "category": ["Spanish", "Brewery"]
    }
  ]
}
           ATTRIBUTE ACCESS  DESCRIPTION 
rid
string
public A unique identifier for the restaurant this directory refers to. This field will only be present for restaurants that are members of the OpenTable network.
name
string
public The name of the restaurant.
latitude
string
public The latitude of the restaurant.
longitude
string
public The longitude of the restaurant.
address
string
public The address of the restaurant.
address2
string
public The second address line of the restaurant.
city
string
public The city in which the restaurant is located.
state
string
public The state or province in which the restaurant is located.
postal_code
string
public The zip code or postal code for the restaurant.
country
string
public The country in which the restaurant is located.
phone_number
string
public The restaurant phone number
metro_name
string
public The area of the city in which the restaurant is located
reservation_url
string
public The restaurant profile page url
profile_url
string
public The restaurant profile page url
is_restaurant_in_group
boolean
public Set to true when the restaurant is a member of the restaurant group associated with the partner.
aggregate_score
string
public Aggregate score of the restaurant, out of 5.
price_quartile
string
public Qualitative pricing of the restaurant, measured in "$". Maximum "$$$$".
review_counnt
integer
public Number of reviews that the restaurant has.
category
array[string]
public Food categories.

The following table outlines the applicable query parameters for this endpoint.

        PARAMETER ACCESS  DESCRIPTION 
offset
integer
public The offset to fetch results at.
limit
integer
public The maximum number of results to return. If this parameter is not specified the API will return up to 100 directory results per call.
country
string
public The API will only return restaurants that exist in the specified country.