Discover Trends in School Lettings – Free 2024 Report Available

Book Demo
Sign In

Bookteq Developer Documentation – Viewing the Calendar

There are a few APIs required to build a calendar. The simplest of these is the timetables API which returns opening times for a Venue by facility

Timetables API

GET /api/timetables?venue=<uuid>&starts=2024-11-12&ends=2024-11-12 HTTP/1.1
Accept: application/ld+json

You can specify a period of time up to a week to retrieve a list of the timetables in this format:

{
    "@context": "/api/contexts/Timetable",
    "@id": "/api/timetables",
    "@type": "hydra:Collection",
    "hydra:member": [
        {
            "@id": "/api/timetables/556f1c9c-18fc-4ceb-aa59-4aa048bfc2b3:2024-11-12",
            "@type": "Timetable",
            "facility": {
                "@id": "/api/facilities/556f1c9c-18fc-4ceb-aa59-4aa048bfc2b3",
                "@type": "Facility",
                "id": "556f1c9c-18fc-4ceb-aa59-4aa048bfc2b3",
                "name": "3G 5-a-side A"
            },
            "id": "556f1c9c-18fc-4ceb-aa59-4aa048bfc2b3:2024-11-12",
            "date": "2024-11-12",
            "closedAt": [
                [
                    "00:00",
                    "05:00"
                ],
                [
                    "21:00",
                    "24:00"
                ]
            ],
            "openAt": [
                [
                    "05:00",
                    "21:00"
                ]
            ]
        },
        ...
    ]
}

This returns two lists, one of ‘closed’ times and one of ‘open’ times. This handles any number of complicated opening hours (e.g. open between 10am and 4pm, then open again at 6pm until 10pm). closedAt and openAt are mirrors of each other, so use which ever one makes the most sense for your application. Each element in the list is a set of two times ["<from>", "<to>"] which correlates to when the facility is open. If the list is empty, the facility is not open. Opening times are not global, so Facility A can be open even when Facility B is shut for example.

Events API

Once you have retrieved the opening times you can retrieve a list of the events. As there are lots of different types of event, we have a generic ReadOnlyEvent type which has a smaller set of properties, and describes what kind of event it is.

To retrieve a list of events for a specific day you can run this request:

GET /api/events?venue=<uuid>&eventStart=2024-11-12&eventEnd=2024-11-13 HTTP/1.1
Accept: application/ld+json

Which will return a list of events over the given timespan (exclusive of the end date). You can also supply times to get a shorter list of events:

GET /api/events?venue=<uuid>&eventStart=2024-11-12T10:00:00&eventEnd=2024-11-12T13:00:00 HTTP/1.1
Accept: application/ld+json

Or if you just need a specific type of event you can filter by that as well:

GET /api/events?venue=<uuid>&eventStart=2024-11-12T10:00:00&eventEnd=2024-11-12T13:00:00&type=multi_booking HTTP/1.1
Accept: application/ld+json

These requests will return a list of the events:

{      
  "@context": "/api/contexts/ReadOnlyEvent",
  "@id": "/api/events",          
  "@type": "hydra:Collection",   
  "hydra:member": [     
    {   
      "@id": "/api/events/46c70769-e23d-4677-9241-7e3d039b7e40",
      "@type": "ReadOnlyEvent",       
      "paid": false,           
      "blockedBy": [],  
      "addOns": 0,
      "additionalQuestions": 2,
      "facilityName": "3G 5-a-side A",
      "id": "46c70769-e23d-4677-9241-7e3d039b7e40",
      "type": "multi_booking",                    
      "facility": "/api/facilities/d8ac6815-6949-4b20-9440-248b1221a887",
      "name": "Alice Foo",
      "from": "2024-11-12T09:30:00+00:00",
      "to": "2024-11-12T10:00:00+00:00",
      "link": {
        "@id": "/api/bookings/46c70769-e23d-4677-9241-7e3d039b7e40",
        "@type": "Booking"
      }
    },
    ...
  ],

For simply displaying data we recommend using the facilityName, name, from and to properties to display on another calendar, or for other reporting. The link property describes what kind of entity this event is, such as a Booking, Session or Custom Event. Blocked events do not have a link as they are generated at runtime and simply reflect space taken by other events.

The type property allows you to quickly see what type of event this is. The event types are as follows:

  • booking and multi_booking
  • session and multi_session
  • reservation and multi_reservation
  • custom
  • blocking
  • blocked

from and to are scoped to the Timezone of the Venue, so will have the correct +01:00 for BST and +00:00 for GMT.

addOns and additionalQuestions describes how many Add Ons or Additional Questions are attached to this booking/session.

paid is true when a booking or session has been fully paid, or is on a payment plan. Free bookings also come through as paid.

blockedBy contains a list of events which happen at the same time in the same location. Bookteq does not stop you from placing two events at the same time, but it will warn you when you try to do this. Below you can see an example of an event which describes the facility being blocked by a booking in another facility:

    {                       
      "@id": "/api/events/fa260407-8ec0-5c45-b18e-5570c8156782",
      "@type": "ReadOnlyEvent",
      "paid": false,
      "blockedBy": [       
        {                  
          "@id": "/api/events/46c70769-e23d-4677-9241-7e3d039b7e40",
          "@type": "ReadOnlyEvent",
          "paid": false,
          "blockedBy": [],       
          "addOns": 0,           
          "additionalQuestions": 2,
          "facilityName": "3G 5-a-side A",
          "id": "46c70769-e23d-4677-9241-7e3d039b7e40",
          "type": "multi_booking",    
          "facility": "/api/facilities/d8ac6815-6949-4b20-9440-248b1221a887",
          "name": "Alice Foo",
          "from": "2024-11-12T09:30:00+00:00",
          "to": "2024-11-12T10:00:00+00:00"
        }
      ],
      "addOns": 0,
      "additionalQuestions": 0,                   
      "facilityName": "3G 11-a-side",
      "id": "fa260407-8ec0-5c45-b18e-5570c8156782",
      "type": "blocked",
      "facility": "/api/facilities/e9a333ef-0dc6-4e1a-a538-c6fcf96b3b40",
      "name": "3G 5-a-side A",
      "from": "2024-11-12T09:30:00+00:00",
      "to": "2024-11-12T10:00:00+00:00",
      "link": []
    }