Bookings

Search booking availability

Bookable slots for a party at a granted location inside a venue-local window (at most 31 days), in start order.

此内容尚不支持你的语言。

GEThttps://api.maple.inc/v1/locations/{locationId}/booking_availabilityAPI key

Bookable slots for a party at a granted location inside a venue-local window (at most 31 days), in start order. Standard slots have experience: null; where the location offers experiences, their slots are listed too, each naming its experience, and experience_id narrows the search to one. Every slot carries an opaque signed slot_token: pass it unchanged to POST /booking_holds, never rebuild slot parameters yourself. Quotes are bound to the partner channel and expire after 15 minutes. Typed outcomes (party_size_out_of_bounds with the bounds, outside_booking_window, large_party_inquiry_required with the venue’s inquiry contact, bookings_not_enabled) come back as 422 with a code. Requires bookings:read.

Authorization

Send your API key as Authorization: Bearer <key>: mpk_test_… against the sandbox (https://api.staging.maple.inc/v1), mpk_live_… against production. See Authentication. The samples read the key from MAPLE_KEY and the base URL from MAPLE_BASE, as set up in the Quickstart.

Parameters

locationId string path required
party_size string query required
start string query required
end string query required
changing_booking_id string or null query
experience_id string or null query

Responses

200 OK

object string required

Always list.
data object[] required
data[].object string required

Always booking_slot.
data[].slot_token string required
data[].starts_at string required
data[].starts_at_local string required
data[].duration_minutes number or null required
data[].area object or null required

The seating area the slot is quoted in, when the provider names one.
data[].area.ref string required
data[].area.name string or null required
data[].cancellation_policy object or null required
data[].cancellation_policy.type string required
data[].cancellation_policy.currency string or null required

ISO-4217.
data[].cancellation_policy.policy_text string or null required
data[].cancellation_policy.tiers object[] required
data[].cancellation_policy.tiers[].within_hours_before_start number required
data[].cancellation_policy.tiers[].basis string required

per_party or per_person.
data[].cancellation_policy.tiers[].amount_cents number or null required
data[].cancellation_policy.tiers[].percent_bps number or null required

Basis points of the party value, when the fee is a percentage.
data[].cancellation_policy.deposit object or null required
data[].cancellation_policy.deposit.amount_cents number required
data[].cancellation_policy.deposit.currency string required
data[].cancellation_policy.deposit.basis string required
data[].experience object or null required

The experience this slot books, or null for a standard reservation. The slot token is bound to it: holding and booking the slot books the experience.
data[].experience.id string required

The experience id; pass it as experience_id to search only its slots.
data[].experience.name string required
data[].experience.description string or null required
data[].experience.prepayment_required boolean required

The experience asks for payment up front. Maple cannot take payment yet, so holding such a slot answers 422 payment_instrument_required: show it, but offer a standard slot to book.

Errors

400 Bad request DeveloperApiBadRequest
401 Unauthorized DeveloperApiUnauthorized
403 Forbidden DeveloperApiForbidden
404 Not found DeveloperApiNotFound
409 Conflict DeveloperApiConflict
422 Unprocessable DeveloperApiUnprocessable
429 Too many requests DeveloperApiRateLimited

Every error body names the error in _tag, explains it in message, and says where to report it in feedback. See Errors.

A 429 also sends Retry-After: Seconds to wait before retrying; also returned as retry_after in the body.

Search booking availability

curl "$MAPLE_BASE/locations/str_123/booking_availability?party_size=2&start=2026-11-20T18%3A00&end=2026-11-20T22%3A00" \
  -H "Authorization: Bearer $MAPLE_KEY"

import os
import requests

r = requests.get(
    f"{os.environ['MAPLE_BASE']}/locations/str_123/booking_availability?party_size=2&start=2026-11-20T18%3A00&end=2026-11-20T22%3A00",
    headers={"Authorization": f"Bearer {os.environ['MAPLE_KEY']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

const res = await fetch(`${process.env.MAPLE_BASE}/locations/str_123/booking_availability?party_size=2&start=2026-11-20T18%3A00&end=2026-11-20T22%3A00`, {
  headers: {
    Authorization: `Bearer ${process.env.MAPLE_KEY}`,
  },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

{
  "object": "list",
  "data": [
    {
      "object": "booking_slot",
      "slot_token": "string",
      "starts_at": "string",
      "starts_at_local": "string",
      "duration_minutes": 1.5,
      "area": {
        "ref": "string",
        "name": "string"
      },
      "cancellation_policy": {
        "type": "string",
        "currency": "USD",
        "policy_text": "string",
        "tiers": [
          {
            "within_hours_before_start": null,
            "basis": "string",
            "amount_cents": null,
            "percent_bps": null
          }
        ],
        "deposit": {
          "amount_cents": null,
          "currency": "USD",
          "basis": "string"
        }
      },
      "experience": {
        "id": "string",
        "name": "string",
        "description": "string",
        "prepayment_required": true
      }
    }
  ]
}

{
  "_tag": "DeveloperApiBadRequest",
  "code": "string",
  "message": "string",
  "feedback": "string"
}