View Categories

public-bookings

3 min read

Public bookings contain the same information as is available in the public calendar. They do not include booking requests.

List of Methods #

In the following endpoints, {slug} needs to be replaced with the same slug as used in the Calendar URL (see Settings -> Venue Details). For example, if your Calendar URL is https://app.myhallwizard.com/dakeford-village-hall, the slug is dakeford-village-hall.

MethodEndpoint
Retrieve upcoming public bookingsGET https://app.myhallwizard.com/api/v0/{slug}/public-bookings

The methods are described below.

Attributes of the public-booking object #

The public-bookings object looks like this:

{
    "id": 77957,
    "uuid": "fce1ebcc-1571-414a-9607-95cdb02b5985",
    "name": "Art Group",
    "confirmed": 1,
    "private": 0,
    "booking_dt": "2022-09-09",
    "start_tm": "14:00:00",
    "end_tm": "16:00:00",
    "details": "<p>The Art Group meets every Friday afternoon between 2pm and 4pm.&nbsp; New members are always welcome.</p>\r\n<p>Contact Jane Doe on 01234 567890 for more information.&nbsp;</p>",
    "room_names": "Main Hall, Side Room",
    "created_at": "2022-09-09T10:23:43.000000Z",
    "updated_at": "2022-09-09T10:26:28.000000Z"
}

Attributes in the object are as follows:

  • id -internal id of the booking (provided for compatibility when we build a full API in the future)
  • uuid – public id of the booking
  • name – the booking name. If the booking is private, name is always “Private booking”. For provisional bookings, there is no indication of this in the name field – the client is responsible for determining how provisional bookings are displayed based on the confirmed attribute
  • confirmed – 1 if the booking is confirmed, 0 if it is provisional
  • private – 0 if the booking is public, 1 if it is private
  • booking_dt – the date of the booking in YYYY-MM-DD format
  • start_tm – start time of the booking in HH:MM:SS format using the local timezone
  • end_tm – end time of the booking in HH:MM:SS format using the local timezone
  • details – the details field as an HTML string. If the booking is private, the details field is always null
  • room_names – the names of the rooms booked, e.g. “Main Hall, Side Room”
  • created_at – the date and time the booking was created
  • updated_at – the date and time the booking was last updated

If the venue is integrated with HeatingSave, there will be an extra attribute:

  • temperature – the temperature set for the booking in °C. If not temperature was set, this will be null.

Methods #

Retrieve upcoming public bookings #

This method retrieves an array of upcoming public bookings starting from today onwards, sorted by booking_dt and start_tm. Bookings today which have already ended are excluded. By default, only public and confirmed bookings are retrieved, though this can be overridden with parameters.

No authentication is needed to use this API, therefore only publicly available information is returned. For example, extras and administration notes are not returned.

As for the public calendar, the venue needs to have its public calendar enabled, and be on a free trial or subscribed.

Endpoint #

GET https://app.myhallwizard.com/api/v0/{slug}/public-bookings

Parameters #

The endpoint can take the following parameters:

  • days – number of days data to retrieve starting from today (e.g. days=7 returns 7 days of data. If today is Friday, this would be public bookings through until next Thursday). Valid values are 1 to 365. Default is 5.
  • limit – the maximum number of bookings to retrieve. Valid values are 1 to 1000. Default limit is 100.
  • include_private – set to 1 to include private bookings in the result set, or 0 to exclude them. Default is 0.
  • include_provisional – set to 1 to include provisional bookings in the result set, or 0 to exclude them. Default is 0
  • updated_since – restricts the result set to only include bookings updated since the date and time specified. Use ISO 8601 formatted date/time, within the UTC timezone. Example: GET https://app.myhallwizard.com/api/v0/{slug}/public-bookings?updated_since=2024-02-13T07:25:00Z.

HTTP response #

We use standard HTTP response codes. A successful call will return an HTTP code 200. Any other return code should be treated as an exception. Codes in the 400 series represent something wrong with your query – check the response body for more information. Codes in 500 series mean something went wrong in our server.

Responses you are most likely to encounter for this API call are:

  • 200 – OK
  • 400 – Bad Request – one of the parameters in your API call failed validation
  • 403 – Forbidden – usually because the public calendar is not enabled for your venue or the venue does not have an active subscription. This error can also occur if our firewall blocks your call; contact HallWizard Support for assistance in this instance.
  • 404 – Not Found – usually means the slug is incorrect

Sample response body #

[
    {
        "id": 77957,
        "uuid": "fce1ebcc-1571-414a-9607-95cdb02b5985",
        "name": "Art Group",
        "confirmed": 1,
        "private": 0,
        "booking_dt": "2022-09-09",
        "start_tm": "14:00:00",
        "end_tm": "16:00:00",
        "details": "<p>The Art Group meets every Friday afternoon between 2pm and 4pm.&nbsp; New members are always welcome.</p>\r\n<p>Contact Jane Doe on 01234 567890 for more information.&nbsp;</p>",
        "room_names": "Main Hall, Side Room",
        "created_at": "2022-09-09T10:23:43.000000Z",
        "updated_at": "2022-09-09T10:26:28.000000Z"
    },
    {
        "id": 36498,
        "uuid": "c0751e0f-d95b-4baa-bdb0-03528b648c6c",
        "name": "Brass Band",
        "confirmed": 1,
        "private": 0,
        "booking_dt": "2022-09-10",
        "start_tm": "19:30:00",
        "end_tm": "22:00:00",
        "details": null,
        "room_names": "Main Hall",
        "created_at": "2022-04-11T16:33:28.000000Z",
        "updated_at": "2022-08-25T07:46:08.000000Z"
    }
]