Introduction
Timekit offers two different ways of querying for availability.
Free until booked: Where a resource is available until a booking reserves time in the calendar, usually general business-rules like opening-hours also applies.
Group bookings: Where an available time-slot is defined on beforehand, with a limited number of seats available.
In this article we'll be covering the first type: Free until booked, and how you can configure Timekits Availability engine to help you create your desired booking experience. Please refer to this tutorial for group bookings if that is more in line with your use-case.
FindTime
Timekit utilizes our Availability engine to find availability for a resource. It works by requesting the /availability endpoint with a set of params telling the engine which resource, when, how and for how long.
A request to /availability could look like this:
curl --request POST \
--url https://api.timekit.io/v2/availability \
--header 'Content-Type: application/json' \
--user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
--data '{
"resources": ["78a4d873-2a68-41c6-bdd4-c0ca5b35efd3"],
"mode": "mutual",
"constraints": [
{"specific_day_and_time":{"day":"Monday","start":9,"end":13}},
{"specific_day_and_time":{"day":"Wednesday","start":10,"end": 16}}
],
"to": "2 weeks",
"length": "30 minutes"
}'
Let's break it down:
in the request above you'll see that we are have something called resources: This is telling Availability which of your resources it needs to look at, if you provide more than one ID, the engine will look for mutual availability(defined by "mode"), which means finding timeslots where both resources are available. If you want a query where any one of a list of resources are available, just change the mode to "roundrobin_random" or "roundrobin_prioritized" if you prooritize one resource over the other.
Constraints
If you just supply a resources and no constraints, Availability will return all available times 24/7. This is usually not what we're looking for. So we'll apply our constraints: to limit availability to only look at Monday between 9 and 13 and Wednesday between 10
and 16 (note we are using 24h clock).
You can see the full API reference for how to format your constraints here: https://developers.timekit.io/reference#constraints
Time-slot length and search-space
Finally you can see we have included "to": "2 weeks" and "length": "30 minutes" at the bottom of the request. This tells Availability that it needs to look 2 weeks into the future and look for available time-slots of 30 minutes length.
The search-space will default start from the next full hour, but you can modify this with the "from" parameter, like this: "from": "1 day" which would mean that the search-space would start tomorrow.
Ok, let's look at the response:
{
"data": [
{
"start": "2015-03-24T15:00:00+01:00",
"end": "2015-03-24T16:00:00+01:00",
"resources": [
{
"id": "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3",
"name": "Marty McFly",
"timezone": "America\/Los_Angeles"
}
]
},
{
"start": "2015-03-24T21:45:00+01:00",
"end": "2015-03-24T22:45:00+01:00",
"resources": [
{
"id": "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3",
"name": "Marty McFly",
"timezone": "America\/Los_Angeles"
}
]
},
{
"start": "2015-03-25T07:30:00+01:00",
"end": "2015-03-25T08:30:00+01:00",
"resources": [
{
"id": "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3",
"name": "Marty McFly",
"timezone": "America\/Los_Angeles"
}
]
},
{
"start": "2015-03-25T16:30:00+01:00",
"end": "2015-03-25T17:30:00+01:00",
"resources": [
{
"id": "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3",
"name": "Marty McFly",
"timezone": "America\/Los_Angeles"
}
]
},
{
"start": "2015-03-25T18:15:00+01:00",
"end": "2015-03-25T19:15:00+01:00",
"resources": [
{
"id": "78a4d873-2a68-41c6-bdd4-c0ca5b35efd3",
"name": "Marty McFly",
"timezone": "America\/Los_Angeles"
}
]
}
]
}When requesting the endpoint correct you will receive a 200 OK response in JSON format with all the available times that match your request.
For a full reference on the /availability endpoint please refer to the API reference.
Next steps
The next natural step after querying for availability is to book the resource at one of the time-slots, for an introduction to bookings please read this article. If you just want a tutorial on how to create bookings through API please refer to this tutorial.