Hi, developer!

This is the documentation for the tablebooker API.
Do you want to use this API? Contact us at dev@tablebooker.be.


Content Types

The tablebooker API supports a bunch of different request/response formats, including XML and JSON.

You can change the content type of the response by appending the format to the base URL, or by adding the format parameter to the request. This means your URLs can look like this:

/api.tablebooker.be/v1/restaurants/info.xml
/api.tablebooker.be/v1/restaurants/info?format=json

You can also set the HTTP Accept header to specify the format.

$ curl -H "Accept: application/xml" /api.tablebooker.be/v1/restaurants

Multilingual Support

The tablebooker API will automatically parse the HTTP Accept-Language header and provide the required language in the responses. Currently only Dutch (nl), French (fr) and English (en) are supported.

$ curl -H "Accept-Language: nl" /api.tablebooker.be/v1/...

API Key

In order to connect and use our API, you need to request an API key. You should set your API key in the header of every request you make.

$ curl -H "X-API-KEY: your_key_here" /api.tablebooker.be/v1/...

Restaurant Information

The restaurant information API returns all public information on a specific restaurant. The base URL for this GET data source is:

/api.tablebooker.be/v1/restaurants/info

The restaurant can be specified in multiple ways. The easiest way is to use the tablebooker ID of the restaurant. The tablebooker ID is the 7+ digit ID you can find in the URL of the restaurant page on www.tablebooker.be. The tablebooker ID can be added to the info URL as an URL segment or a GET parameter:

/api.tablebooker.be/v1/restaurants/info/1234567
/api.tablebooker.be/v1/restaurants/info?tablebooker_id=1234567

Additionally, you can use IDs of other services, such as Foursquare, to specify the restaurant. Currently, we support the following services:

Service Parameter URL
tablebooker tablebooker_id www.tablebooker.be
Resto resto_id (715) 664-8341
Yelp yelp_id 6396220085
Foursquare foursquare_id (226) 515-6301
Foodspotting foodspotting_id www.foodspotting.com

The restaurant search API returns a list of tablebooker restaurants near a location, optionally matching a search term. The base URL for this GET data source is:

/api.tablebooker.be/v1/restaurants/search

The location of the restaurants can be specified using a city name or a latitude/longitude value. Optionally, an extra search term can be added to filter the returned restaurants.

By default, the restaurant list is limited to pages of 20 restaurants. Using the page parameter, additional restaurants can be fetched. The rpp parameter can be used to change the number of restaurants per page.

Parameters

All parameters are optional, unless otherwise indicated.

city Antwerpen Required unless latlng is specified. Name of the city in which the user is looking for restaurants.
latlng 44.3,37.2 Required unless city is specified. Latitude and longitude of the user's location, separated with a comma. If this parameter is specified, a distance field (in kilometers) is added to every restaurant in the result list.
radius 5 Limit results to restaurants within this number of kilometers of the specified location. Default is 10 kilometers, maximum is 25 km.
query leeuw Limit results to restaurant names that match this search term.
page 4 The page number of the requested page. Defaults to the first page (with page number 1).
rpp 10 Results per page. Default is 20.

Restaurant Availability

The restaurant availability interface allows you to retrieve the availability of one or more restaurants on a given day for a certain amount of people. The base URL for this GET data source is:

/api.tablebooker.be/v1/restaurants/availability

The API method returns for each restaurant the general availability (boolean), a general message (which should be shown to the user if present) and a list of all possible arrival times during opening hours. If the time parameter is specified, only this time slot is returned. For each of the arrival times, the availability for this time slot is shown (boolean) together with a list of messages that have to be shown to the end user when the user selects this arrival time.

Parameters

All parameters are optional, unless specified otherwise.

tablebooker_id 0003487,0001234 Required A single tablebooker ID, or a comma-separated list of tablebooker IDs.
date 2018-11-21 Required Show the availability for this date. Specified in the format YYYY-MM-DD.
guests 4 Required Show the availability for this amount of guests.
time 19:00 Show the availability for this time only.

Restaurant Menu

The restaurant menu API returns the menu information of a restaurant. The base URL for this GET data source is:

/api.tablebooker.be/v1/restaurants/menu

The restaurant can be specified by providing the tablebooker_id. The tablebooker ID is the 7+ digit ID you can find in the URL of the restaurant page on (754) 600-4816. The tablebooker ID can be added to the info URL as an URL segment or a GET parameter:

/api.tablebooker.be/v1/restaurants/menu/1234567
/api.tablebooker.be/v1/restaurants/menu?tablebooker_id=1234567
tablebooker_id 1234567 Required unless the id is specified as an URL segment. A single tablebooker ID.

Send message to restaurant

The "Restaurant Message" API makes it possible to send a message to the restaurant.
The base URL for this POST data source is:

/api.tablebooker.be/v1/restaurants/message/{restaurantId}

Authentication

Basic auth is required for this call.

Parameters

subject "My message subject" Optional subject line. A default subject will be used when this is not filled in.
message "My message for the restaurant" Required The actual message.
reservation_id 00124356 An optional reservation id. When the id is passed, the message will be linked to the reservation.
sender_name John Doe Optional/Required The name of the sender. This field is only required when no Reservation Id is supplied.
sender_email john@doe.com Optional/Required The email address of the sender. This field is only required when no Reservation Id is supplied.

Response

The response contains a status field, which is either "OK" when the message was send successfully, or "error" when something went wrong.

When the message was successful it also returns the message Id.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_reservation 404 The specified reservation is unknown and could not be updated.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Making a reservation

The "New reservation" API makes it possible to add a new reservation to the calendar of a restaurant.
The base URL for this POST data source is:

/api.tablebooker.be/v1/reservations/new

Parameters

tablebooker_id 0001234 Required The tablebooker ID of the restaurant in which the reservation should be made.
date 2018-11-21 Required Make a reservation on this day. Specified in the format YYYY-MM-DD.
time 19:00 Required Make a reservation at this arrival time. Specified in the format HH:MM. The restaurant should accept reservations at this time, and the time slot should be available.
guests 4 Required Make a reservation for this amount of guests.
customer_id 12345678 The customer ID that was returned by the login API.
customer_token f94e59...e405ac The customer token that was returned by the login API.
customer_type personal Required unless customer_id and customer_token are specified.
The type of the customer making a reservation, either "personal" or "business".
customer_lastname Janssens Required unless customer_id and customer_token are specified.
The last name of the customer for which a reservation is made.
customer_firstname Koen The first name of the customer for which a reservation is made.
customer_phone 031234567 Required unless customer_id and customer_token are specified.
The phone number of the customer for which a reservation is made.
customer_email koen.janssens@exemple.be Required unless customer_id and customer_token are specified.
The email address of the customer for which a reservation is made.
customer_company tablebooker CVBA Required when customer_type is "business", unless customer_id and customer_token are specified.
The company for which a reservation is made.
customer_vat BE0849393861 Required when customer_type is "business", unless customer_id and customer_token are specified.
The VAT number of the company for which a reservation is made.
customer_message This is a message An optional message to go with the reservation. For example a message about allergies or seating.

Response

The response contains a status field, which is either "OK" when the reservation has been made successfully, or "error" when something went wrong.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_restaurant 404 The specified restaurant is unknown or doesn't accept reservations from you.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
no_table_available 403 There is no table available for making this reservation. Check again using the availability API before making a reservation attempt.
invalid_customer_credentials 403 Could not authenticate the customer using the customer_id and customer_token. Prompt the user to log in again.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Update a reservation

The "Update reservation" API makes it possible to update an existing reservation.
The base URL for this POST data source is:

/api.tablebooker.be/v1/reservations/update/{reservationId}

Authentication

Basic auth is required for this call.

Parameters

date 2018-11-21 Required Make a reservation on this day. Specified in the format YYYY-MM-DD.
time 19:00 Required Make a reservation at this arrival time. Specified in the format HH:MM. The restaurant should accept reservations at this time, and the time slot should be available.
guests 4 Required Make a reservation for this amount of guests.

Response

The response contains a status field, which is either "OK" when the reservation has been updated successfully, or "error" when something went wrong.

When the change was successfull it also returns the reservation Id, the reservation status and the reservation url.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_reservation 404 The specified reservation is unknown and could not be updated.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
no_table_available 403 There is no table available for making this reservation. Check again using the availability API before making a reservation attempt.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Cancel a reservation

The "Cancel reservation" API makes it possible to cancel an existing reservation.
The base URL for this POST data source is:

/api.tablebooker.be/v1/reservations/cancel/{reservationId}

Authentication

Basic auth is required for this call.

Parameters

No additional parameters

Response

The response contains a status field, which is either "OK" when the reservation has been cancelled successfully, or "error" when something went wrong.

When the cancellation was successful then the response also contains the reservation id, reservation status and reservation url.

When returning an error response, this response is accompanied with an error_code field. This error code can be used to handle the error correctly, and to return the appropriate error message to the customer. In the table below you can find a list of possible error codes.

error_code HTTP Status code Explanation
unknown_reservation 404 The specified reservation is unknown.
invalid_field 400 One of the input fields is invalid or missing. This message is accompanied with an extra field field, which contains the name of the field that is missing or contains invalid input.
no_table_available 403 There is no table available for making this reservation. Check again using the availability API before making a reservation attempt.
invalid_customer_credentials 403 Could not authenticate the customer using the customer_id and customer_token. Prompt the user to log in again.
unexpected_error 500 Something went wrong trying to make this reservation. Contact us at support@tablebooker.be with the request details if this response occurs frequently.

Login

The "Login" API allows a customer to log in into its tablebooker account.
The base URL for this GET data source is:

/api.tablebooker.be/v1/customers/login

Parameters

email tony@tablebooker.be Required Contains the e-mail address of the user that wants to login into its tablebooker account.
password tony123 Required The customer's tablebooker password. Never store this password locally, instead exchange it using this API for a customer_id and customer_token.

Response

The response contains a status field, which is either "OK" when the login was successfull, or "error" when something went wrong.

When the login was successfull, the API returns a customer_id and a customer_token, which can be stored locally for future use. When the status of the API call was "error", you should prompt the user for its login credentials again.

Login with Facebook

The "Login with Facebook" API allows a customer to log in into its tablebooker account using Facebook.
The base URL for this GET data source is:

/api.tablebooker.be/v1/customers/login_with_facebook

Parameters

facebook_id 1037841836 Required Facebook ID of the user logging in.
facebook_access_token dhcj399...e47dtte Required The Facebook access token for the user's Facebook session.

Response

The response contains a status field, which is either "OK" when the login was successfull, or "error" when something went wrong.

When the login was successfull, the API returns a customer_id and a customer_token, which can be stored locally for future use. When the status of the API call was "error", you should prompt the user for its login credentials again.

Information

Retrieve information

The "info" API allows you to fetch customer information. The base URL for this GET data source is:

/api.tablebooker.be/v1/customers/info

Parameters

customer_id 12345678 Required The customer ID that was returned by the login API.
customer_token f94e59...e405ac Required The customer token that was returned by the login API.

If the customer id or customer token is invalid, a 403 error is returned.

Update information

The same "info" API also allows you to update customer information. The base URL for this POST data source is:

/api.tablebooker.be/v1/customers/info

Parameters

customer_id 12345678 Required The customer ID that was returned by the login API.
customer_token f94e59...e405ac Required The customer token that was returned by the login API.
customer_type personal The type of the customer, either "personal" or "business".
customer_firstname Tony The first name that has to be stored in the customer.
customer_lastname Tablebooker The last name that has to be stored in the customer.
customer_company Tablebooker CVBA The company name that has to be stored in the customer (only for "business" customers).
customer_vat BE0849393861 The VAT number that has to be stored in the customer (only for "business" customers).
customer_email tony@tablebooker.be The e-mail address that has to be stored in the customer.
customer_phone 093323323 The phone number that has to be stored in the customer.
customer_gender male The gender of the customer, either "male" or "female".
customer_birthday 1980-01-01 The birthday that has to be stored in the customer, in the format YYYY-MM-DD.

Access reviews from customers that have visited a restaurant.

Get Reviews

/api.tablebooker.be/v1/reviews

Examples

        /api.tablebooker.be/v1/reviews/1234567
/api.tablebooker.be/v1/reviews?restaurant_id=1234567

By default, the reviews list is limited to pages of 20 reviews. Using the page parameter, additional reviews can be fetched. The rpp parameter can be used to change the number of reviews per page.

Parameters

Either the id or restaurant_id are required

id 012345 Required The unique id of a review. When this parameter is provided only a single review is returned.
restaurant_id 012345 Required The unique tablebooker ID of the restaurant. When this parameter is provided all public reviews of the restaurant will be returned.
page 4 The page number of the requested page. Defaults to the first page (with page number 1).
rpp 10 Results per page. Default is 20.

If you are a tablebooker partner and received an API partner key, you have access to all methods of the Restaurant API and gigantocyte discussed above. Through these methods, only restaurants that enabled you as a reservation partner are available, other tablebooker restaurants are invisible.

Furthermore, you also have access to the partner-specific API methods below.

Restaurants

The partner restaurants API returns the list of restaurants that have the partner enabled. The base URL for this GET data source is:

/api.tablebooker.be/v1/partners/restaurants

By default, the restaurant list is limited to pages of 20 restaurants. Using the page parameter, additional restaurants can be fetched. The rpp parameter can be used to change the number of restaurants per page.

Parameters

No parameters are required.

page 4 The page number of the requested page. Defaults to the first page (with page number 1).
rpp 10 Results per page. Default is 20.