Structuring availability data for Reservations

Parameter definitions

As specified in the Availability definition:

  • party_size: The party size that can be accommodated during this time slot. A restaurant can be associated with multiple Slots for the same time, each specifying a different party_size, if for instance 2, 3, or 4 people can be seated with a reservation
  • spots_open: The number of spots currently available for this availability entry
  • spots_total: The total number of spots that the merchant has for this configuration (including those that are not available)

These three parameters work together to build a digital representation of the floor plan. party_size is the number of people each table can hold (there will be an entry for every size a table can accommodate). spots_open and spots_total are counts of how many tables can accommodate that party_size.

Example empty floor plan

Imagine a restaurant with the following floor plan and no active bookings:

Figure 1: Floor plan with no active bookings
Figure 1: Floor plan with no active bookings

The values for party_size, spots_open, and spots_total would be:

party_size spots_open spots_total
4 3 3
5 3 3
6 4 4
7 1 1
8 1 1

The availability feed for one time slot at this merchant would look like:

JSON

{
  "availability": [
        {
          "spots_total": 3,
          "spots_open": 3,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 4
          }
        },
        {
          "spots_total": 3,
          "spots_open": 3,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 5
          }
        },
        {
          "spots_total": 4,
          "spots_open": 4,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 6
          }
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 7
          }
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 8
          }
        }
      ]
}

Example floor plan with a booking

Now imagine that one of the round tables was booked:

Figure 2: Floor plan with one active booking
Figure 2: Floor plan with one active booking

The values for party_size, spots_open, and spots_total would now be:

party_size spots_open spots_total
4 2 3
5 2 3
6 3 4
7 1 1
8 1 1

JSON

{
  "availability": [
        {
          "spots_total": 3,
          "spots_open": 2,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 4
          }
        },
        {
          "spots_total": 3,
          "spots_open": 2,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 5
          }
        },
        {
          "spots_total": 4,
          "spots_open": 3,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 6
          }
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 7
          }
        },
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1535806800,
          "merchant_id": "merch1",
          "resources": {
            "party_size": 8
          }
        }
      ]
}

Specifying dining availability with combined tables support

There are many ways that a restaurant could combine tables to support larger groups. You are expected in your feeds to specify spots_open and spots_total in a way that accurately reflects whether you can accept parties of a given size. What follows is one example of how you can specify combining tables. Your feeds may differ somewhat in how this calculation is made and it is acceptable for you to specify spots_open and spots_total in a way that matches your business logic.

If a restaurant supports combining tables to form a larger party, you can update your spots_open and spots_total to reflect this.

Say a restaurant can combine two small tables to seat a party of 7-10 people.

Figure 3: Floor plan with no active bookings
Figure 3: Floor plan with no active bookings

In the case of no active bookings, the values for party_size, spots_open, and spots_total are:

party_size spots_open spots_total
4 3 3
5 3 3
6 4 4
7 1 1
8 1 1
9 1 1
10 1 1

Now, with the same floor plan, a booking is made for a party size of 10 that combines two small tables.

Figure 4: Floor plan with one active booking spanning two tables
Figure 4: Floor plan with one active booking spanning two tables

Then, the values for party_size, spots_open, and spots_total are now:

party_size spots_open spots_total
4 1 3
5 1 3
6 2 4
7 1 1
8 1 1
9 0 1
10 0 1