# 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: "2025-12-07T17: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

      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
      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: "2025-12-07T17:00:00.000Z"
          schema:
            type: string
            format: date-time
        - name: datetime_min
          in: query
          description: Lower-bound datetime for range query.
          required: false
          example: "2025-12-07T16:00:00.000Z"
          schema:
            type: string
            format: date-time
        - name: datetime_max
          in: query
          description: Upper-bound datetime for range query.
          required: false
          example: "2025-12-07T16:00:00.000Z"
          schema:
            type: string
            format: date-time
        - name: date
          in: query
          description: Desired date in which to search availability.
          required: false
          example: "2025-12-07"
          schema:
            type: string
            format: date
        - name: date_min
          in: query
          description: Lower-bound date for range query.
          required: false
          example: "2025-12-07"
          schema:
            type: string
            format: date
        - name: date_max
          in: query
          description: Upper-bound date for range query.
          required: false
          example: "2025-12-09"
          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
      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: "2025-12-07T17:00:00.000Z"
          schema:
            type: string
            format: date-time
        - name: datetime_min
          in: query
          description: Lower-bound datetime for range query.
          required: false
          example: "2025-12-07T16:00:00.000Z"
          schema:
            type: string
            format: date-time
        - name: datetime_max
          in: query
          description: Upper-bound datetime for range query.
          required: false
          example: "2025-12-07T16:00:00.000Z"
          schema:
            type: string
            format: date-time
        - name: date
          in: query
          description: Desired date in which to search availability.
          required: false
          example: "2025-12-07"
          schema:
            type: string
            format: date
        - name: date_min
          in: query
          description: Lower-bound date for range query.
          required: false
          example: "2025-12-07"
          schema:
            type: string
            format: date
        - name: date_max
          in: query
          description: Upper-bound date for range query.
          required: false
          example: "2025-12-09"
          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
      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: "2025-12-07T17: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
      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

  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: []
