# Test and edit this file at https://editor.swagger.io/
openapi: 3.0.0
info:
version: 1.0.0
title: TableCheck API - Availability V1
description: The Availability API is used to obtain near real-time table availability for online reservation booking.
termsOfService: https://tablecheck.atlassian.net/wiki/spaces/API/pages/61571353/TableCheck+API+Terms+of+Service
externalDocs:
description: Implementation Guide
url: https://tablecheck.atlassian.net/wiki/spaces/API/pages/46301274/Availability+v1
servers:
- url: https://api.tablecheck.com/api/availability/v1/
description: Production (uses live data)
paths:
/shops:
get:
summary: Search for availability across all shops
operationId: listShops
tags:
- shops
parameters:
- name: pax
in: query
description: Desired number of guests for which to search for availability.
required: false
example: 2
schema:
type: number
format: integer
- name: datetime
in: query
description: Desired datetime around which to search for availability.
required: false
example: "2026-07-06T17:00:00.000Z"
schema:
type: string
format: date-time
- name: mini
in: query
description: If true, returns only availablity without including shop info.
required: false
schema:
type: boolean
- name: ids
in: query
description: Array or comma-separated list of specific IDs to return.
required: false
schema:
type: string
format: bson-id
- name: slugs
in: query
description: Array or comma-separated list of specific slugs to return.
required: false
schema:
type: string
- name: page
in: query
description: The zero-based page number. Used for pagination.
required: false
schema:
type: number
format: integer
minimum: 0
- name: per_page
in: query
description: Number of items to return at once. Used for pagination.
required: false
schema:
type: number
format: integer
default: 20
minimum: 1
maximum: 100
- name: sort
in: query
description: The field by which to sort the results. Distance sort is applied only if geo parameters are present.
required: false
schema:
type: string
default: distance
enum:
- distance
- slug
- name
- budget_lunch
- budget_dinner
- name: sort_order
in: query
description: asc or desc.
required: false
schema:
default: asc
enum:
- asc
- desc
type: string
- name: name
in: query
description: Filter by the shop name.
required: false
schema:
type: string
- name: geo_latitude
in: query
description: The latitude of the geocode center point used to evaluate distance query.
required: false
schema:
type: number
format: float
- name: geo_longitude
in: query
description: The longitude of the geocode center point used to evaluate distance query.
required: false
schema:
type: number
format: float
- name: geo_distance
in: query
description: The maximum distance in meters from the geocode center point from which to return results.
required: false
schema:
type: number
format: float
- name: cuisines
in: query
description: Filter by a list of cuisine values (array or comma-separated list)
required: false
schema:
type: string
- name: tags
in: query
description: Filter by a list of tag values (array or comma-separated list)
required: false
schema:
type: string
- name: seat_types
in: query
description: Filters availability by the type of seating, e.g. table, counter, private room, etc. (array or comma-separated list)
required: false
schema:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
- name: smoking
in: query
description: Filters availability by whether the seating allows smoking or not. If unspecified, both smoking and non-smoking are allowed.
required: false
schema:
type: string
enum:
- smoking
- non_smoking
- name: service_modes
in: query
description: Service mode selection of dining, pickup, etc. (array or comma-separated list)
required: false
schema:
type: string
enum:
- dining
- pickup
- delivery
- voucher
- name: budget_lunch_min
in: query
description: Minimum of lunch budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: budget_lunch_max
in: query
description: Maximum of lunch budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: budget_dinner_min
in: query
description: Minimum of dinner budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: budget_dinner_max
in: query
description: Maximum of dinner budget range filter.
required: false
schema:
type: number
format: float
minimum: 0
- name: address_city
in: query
description: Filter by the shop's address city, ward, or municipality.
required: false
schema:
type: string
- name: address_region
in: query
description: Filter by the shop's address region, state, or province.
required: false
schema:
type: string
- name: address_postal_code
in: query
description: Filter by the shop's address postal code.
required: false
schema:
type: string
- name: address_country
in: query
description: Filter by the shop's address country.
required: false
schema:
type: string
- name: search_after
in: query
description: Use for pagination. Set this value to obtain the next page of results.
required: false
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: A paged array of shops
content:
application/json:
schema:
$ref: "#/components/schemas/ShopsListResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/shops/{shop_id}:
get:
summary: Fetch info of a specific shop. Does not include availability.
operationId: showShopById
tags:
- shops
parameters:
- name: shop_id
in: path
required: true
description: The id or slug of the shop to retrieve
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/ShopShowResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/timetable/{shop_id}:
get:
summary: Fetch availability timetable of a specific shop.
operationId: showTimetableByShopId
tags:
- timetable
parameters:
- name: shop_id
in: path
required: true
description: The id or slug of the shop timetable to retrieve
schema:
type: string
- name: pax
in: query
description: Desired number of guests for which to search for availability.
required: false
example: 2
schema:
type: number
format: integer
- name: datetime
in: query
description: Desired datetime around which to search for availability.
required: false
example: "2026-07-06T17:00:00.000Z"
schema:
type: string
format: date-time
- name: datetime_min
in: query
description: Lower-bound datetime for range query.
required: false
example: "2026-07-06T16:00:00.000Z"
schema:
type: string
format: date-time
- name: datetime_max
in: query
description: Upper-bound datetime for range query.
required: false
example: "2026-07-06T16:00:00.000Z"
schema:
type: string
format: date-time
- name: date
in: query
description: Desired date in which to search availability.
required: false
example: "2026-07-06"
schema:
type: string
format: date
- name: date_min
in: query
description: Lower-bound date for range query.
required: false
example: "2026-07-06"
schema:
type: string
format: date
- name: date_max
in: query
description: Upper-bound date for range query.
required: false
example: "2026-07-08"
schema:
type: string
format: date
- name: time
in: query
description: Desired time of day in which to search availability. Can be specified as time string or integer seconds.
required: false
example: '17:00'
schema:
type: string
format: time-of-day
- name: time_min
in: query
description: Lower-bound time of day for range query. Can be specified as time string or integer seconds.
required: false
example: '15:00'
schema:
type: string
format: time-of-day
- name: time_max
in: query
description: Upper-bound time of day for range query. Can be specified as time string or integer seconds.
required: false
example: '20:00'
schema:
type: string
format: time-of-day
- name: seat_types
in: query
description: Filters availability by the type of seating, e.g. table, counter, private room, etc. (array or comma-separated list)
required: false
schema:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
- name: smoking
in: query
description: Filters availability by whether the seating allows smoking or not. If unspecified, both smoking and non-smoking are allowed.
required: false
schema:
type: string
enum:
- smoking
- non_smoking
- name: service_category_id
in: query
required: false
description: The id of the service category
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/TimetableShowResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/calendar/{shop_id}:
get:
summary: Fetch availability calendar of a specific shop.
operationId: showCalendarByShopId
tags:
- calendar
parameters:
- name: shop_id
in: path
required: true
description: The id or slug of the shop calendar to retrieve
schema:
type: string
- name: pax
in: query
description: Desired number of guests for which to search for availability.
required: false
example: 2
schema:
type: number
format: integer
- name: datetime
in: query
description: Desired datetime around which to search for availability.
required: false
example: "2026-07-06T17:00:00.000Z"
schema:
type: string
format: date-time
- name: datetime_min
in: query
description: Lower-bound datetime for range query.
required: false
example: "2026-07-06T16:00:00.000Z"
schema:
type: string
format: date-time
- name: datetime_max
in: query
description: Upper-bound datetime for range query.
required: false
example: "2026-07-06T16:00:00.000Z"
schema:
type: string
format: date-time
- name: date
in: query
description: Desired date in which to search availability.
required: false
example: "2026-07-06"
schema:
type: string
format: date
- name: date_min
in: query
description: Lower-bound date for range query.
required: false
example: "2026-07-06"
schema:
type: string
format: date
- name: date_max
in: query
description: Upper-bound date for range query.
required: false
example: "2026-07-08"
schema:
type: string
format: date
- name: time
in: query
description: Desired time of day in which to search availability. Can be specified as time string or integer seconds.
required: false
example: '17:00'
schema:
type: string
format: time-of-day
- name: time_min
in: query
description: Lower-bound time of day for range query. Can be specified as time string or integer seconds.
required: false
example: '15:00'
schema:
type: string
format: time-of-day
- name: time_max
in: query
description: Upper-bound time of day for range query. Can be specified as time string or integer seconds.
required: false
example: '20:00'
schema:
type: string
format: time-of-day
- name: seat_types
in: query
description: Filters availability by the type of seating, e.g. table, counter, private room, etc. (array or comma-separated list)
required: false
schema:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
- name: smoking
in: query
description: Filters availability by whether the seating allows smoking or not. If unspecified, both smoking and non-smoking are allowed.
required: false
schema:
type: string
enum:
- smoking
- non_smoking
- name: service_category_id
in: query
required: false
description: The id of the service category
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/CalendarShowResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/availability_tables/{shop_id}:
get:
summary: Fetch availability tables of a specific shop.
tags:
- availability
parameters:
- name: shop_id
in: path
required: true
description: The id or slug of the shop to retrieve
schema:
type: string
- name: pax
in: query
required: true
description: Desired number of guests for which to search for availability.
example: 2
schema:
type: number
format: integer
- name: datetime
in: query
required: true
description: Desired datetime around which to search for availability.
example: "2026-07-06T17:00:00.000Z"
schema:
type: string
format: date-time
- name: seat_types
in: query
description: Filters availability by the type of seating, e.g. table, counter, private room, etc. (array or comma-separated list)
required: false
schema:
type: string
enum: ["open","counter","outside","curtain","private","tatami"]
- name: service_category_id
in: query
required: false
description: The id of the service category
schema:
type: string
- $ref: '#/components/parameters/IncludeFields'
- $ref: '#/components/parameters/ExcludeFields'
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/AvailabilityTableShowResponse"
default:
description: Error response
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: AUTHORIZATION
parameters:
IncludeFields:
name: include_fields
in: query
description: Comma-separated list of fields to include in the response (whitelist). If specified, only the listed fields will be returned. Supports dot notation for nested fields.
required: false
schema:
type: string
example: id,name,addresses.city
ExcludeFields:
name: exclude_fields
in: query
description: Comma-separated list of fields to exclude from the response (blacklist). All fields except the given ones will be returned. Supports dot notation for nested fields.
required: false
schema:
type: string
example: created_at,socials.username
schemas:
Shop:
required:
- id
- name_translations
properties: &SHOP_PROPERTIES
id:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
slug:
type: string
example: my-shop-slug
name_translations:
type: object
format: translations
example:
en: "Paris Cafe"
fr: "Café de Paris"
ja: "カフェデパリ"
alt_name:
type: string
example: "カフェデパリ"
location_name_translations:
type: object
format: translations
example:
en: "Hotel Kyoto"
fr: "Hôtel Kyoto"
ja: "ホテル京都"
alt_location_name:
type: string
example: "ホテルキョウト"
latitude:
type: number
format: float
example: 35.0116
longitude:
type: number
format: float
example: 135.7680
google_place_ref:
type: string
example: "ChIJ39ZjD-GLGGARBF5Aq0l7iPE"
google_place_cid:
description: "DEPRECATED. Use google_place_ref instead."
type: string
example: "Use-google_place_ref-instead"
country:
type: string
format: country
example: JP
currency:
type: string
format: currency
example: JPY
time_zone:
type: string
format: time-zone
example: Asia/Tokyo
phone:
type: string
format: phone-e164
example: "+81355650112"
phone_natl:
type: string
format: phone-national
example: "03-5565-0112"
homepage_url:
type: string
format: url
example: 'https://www.myrestaurant.com/ja'
homepage_url_translations:
type: object
format: translations
example:
en: 'https://www.myrestaurant.com/en'
ja: 'https://www.myrestaurant.com/ja'
tablecheck_shop_url:
type: string
format: url
example: https://www.tablecheck.com/my-shop-slug
tablecheck_booking_url:
type: string
format: url
example: https://www.tablecheck.com/shops/my-shop-slug/reserve
tags:
type: array
example:
- outdoor
- quiet
items:
type: string
cuisines:
type: array
example:
- sushi
- tempura
items:
type: string
budget_lunch:
type: string
format: float
example: "10000.0"
budget_dinner:
type: string
format: float
example: "10000.0"
updated_at:
type: string
format: date-time
content_title_translations:
type: object
format: translations
description: Short catchphrase for the restaurant.
example:
en: "A truly great restuarant"
ja: "本当にすごいレストランです"
content_body_translations:
type: object
format: translations
description: Paragraph of content about the restaurant.
example:
en: "I love this restuarant!"
ja: "このレストラン大好きです！"
show_pax_senior:
description: Whether the venue prefers to allow users to select the "pax_senior" field (number of elderly persons in the party.)
type: boolean
show_pax_child:
description: Whether the venue prefers to allow users to select the "pax_child" field (number of children in the party.)
type: boolean
show_pax_baby:
description: Whether the venue prefers to allow users to select the "pax_baby" field (number of babies in the party.)
type: boolean
pax_senior_age_min:
description: The minimum age for a person to be considered a senior.
type: number
format: integer
example: 65
pax_child_age_max:
description: The maximum age for a person to be considered a child.
type: number
format: integer
example: 12
pax_baby_age_max:
description: The maximum age for a person to be considered a baby.
type: number
format: integer
example: 5
service_categories:
description: The ServiceCategories of the Shop.
type: array
items:
'$ref': "#/components/schemas/ServiceCategory"
address:
$ref: "#/components/schemas/Address"
alt_address:
$ref: "#/components/schemas/Address"
images:
description: List of images depicting the shop. Consistent sizing of images is not guaranteed.
type: array
items:
$ref: "#/components/schemas/ImageEmbed"
image_url:
type: string
format: url
description: (Deprecated) Please use "images" field instead.
Address:
properties:
street:
type: string
example: "2-14-5 Ginza"
street2:
type: string
example: "Dai-27 Chuo Bldg 4F"
city:
type: string
example: "Chuo-ku"
region:
type: string
example: "Tokyo"
postal_code:
type: string
example: "104-0061"
country:
type: string
example: "JP"
ServiceCategory:
properties:
id:
description: Identifer for the ServiceCategory object.
type: string
format: bson-id
example: '5e281bfa7df93f63e0000003'
name_translations:
description: The name of the ServiceCategory.
type: array
example:
en: Sushi Bar
ja: 寿司バー
description_translations:
description: The description of the ServiceCategory.
type: array
example:
en: 'This is the sushi bar at our restaurant.'
ja: 当店の特設寿司バーで至福のひとときをお楽しみください。
image:
description: Image depicting the ServiceCategory. Consistent sizing of images is not guaranteed.
$ref: "#/components/schemas/ImageEmbed"
image_url:
description: (Deprecated) Please use "image" field instead.
type: string
format: url
ImageEmbed:
properties:
id:
description: The database ID of the Image.
type: string
format: bson-id
url:
description: The URL of the image as a large size JPEG.
type: string
format: url
example: https://cdn1.tablecheck.com/images/92a543f5085ea8b1ffbe000a/images/original/image.jpg
dimensions:
description: The dimensions of the image as a large size JPEG.
type: array
example: [1280, 960]
content_type:
description: The MIME content type of the image.
type: string
example: image/jpeg
fingerprint:
description: The fingerprint of the image used for deduplication.
type: string
example: af6515a29e04ac61d4379a3181140647
image_variants:
description: A list of image size variants scaled to different sizes. Note that "original" size variant may be a format other than JPEG.
type: array
items:
$ref: "#/components/schemas/ImageVariant"
tags:
description: Identifier tags associated with the image.
type: array
example: [primary]
created_at:
type: string
format: date-time
ImageVariant:
properties:
variant:
type: string
enum: ["original","large","medium","small"]
url:
type: string
format: url
example: https://cdn1.tablecheck.com/images/92a543f5085ea8b1ffbe000a/images/original/image.jpg
dimensions:
type: array
example: [2000, 1500]
content_type:
description: The MIME content type of the image variant.
type: string
example: image/jpeg
ShopsListResponse:
type: object
properties:
shops:
type: array
items:
$ref: "#/components/schemas/ShopAvailability"
pagination:
$ref: "#/components/schemas/PaginationData"
ShopShowResponse:
type: object
properties:
shop:
$ref: "#/components/schemas/Shop"
ShopAvailability:
properties:
availability:
type: array
example:
- "2018-11-10T02:30:00.000Z"
- "2018-11-10T02:45:00.000Z"
- "2018-11-10T05:30:00.000Z"
availability_cached_at:
type: string
format: date-time
<<: *SHOP_PROPERTIES
TimetableShowResponse:
type: object
properties:
timetable:
type: object
properties:
id:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
slug:
type: string
example: my-shop-slug
availability:
type: array
items:
format: date-time
example:
- "2018-11-10T02:30:00.000Z"
- "2018-11-10T02:45:00.000Z"
- "2018-11-10T05:30:00.000Z"
availability_cached_at:
type: string
format: date-time
CalendarShowResponse:
type: object
properties:
calendar:
type: object
properties:
id:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
slug:
type: string
example: my-shop-slug
availability:
type: array
items:
format: date
example:
- "2018-11-10"
- "2018-11-11"
- "2018-11-13"
availability_cached_at:
type: string
format: date-time
AvailabilityTableShowResponse:
type: object
properties:
timetable:
type: object
properties:
id:
type: string
format: bson-id
example: ae5355ca1fd337ed5d6893e2
slug:
type: string
example: my-shop-slug
tables:
type: array
items:
type: string
format: bson-id
example:
- 65e963e36ff2a92b0fb1fcfd
- 65e963756ff2a92b0fb1fcf6
table_combos:
type: array
items:
type: string
format: bson-id
example:
- 65e963e36ff2a92b0fb1fcfd
- 65e963756ff2a92b0fb1fcf6
PaginationData:
type: object
properties:
search_after:
description: The value to use as the search_after parameter for the next page of results.
type: string
page:
type: number
format: integer
example: 3
per_page:
type: number
format: integer
example: 100
page_count:
type: number
format: integer
example: 8
item_count:
type: number
format: integer
example: 742
Error:
required:
- errors
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
example: not_found
message:
type: string
example: Item not found
security:
- ApiKeyAuth: []