loader

DEVELOPERS > API REFERENCE

Our goal is to make is easy for any app to retrieve availability data from a user's calendar. Because most apps display the information in one of several standard ways (ex: weekly view or "next available timeslot" view) we provide a high-level API that will not just query the calendar for the desired date range but will also structure the resulting data so you can just iterate over the result set and generate the view. This allows you to quickly display the data without having to waste time calculating what's beginning/end of week, the beginning/end of day, or timeslot offsets for every week day.

Of course if you just want the raw data, we also have a low-level API which is the equivalent of what each calendar provider offers. Rather than inventing our own REST interface and JSON response type for the low-level API we adopted the Google Calendar 'freebusy' REST interface. This should make it easy to point code that talks to Google Calendar API to the FreeBusy API and have it just work with many other calendar providers.

Documentation

URL format for FreeBusy APIs:


https://api.freebusy.io/[version]/[api]/[user_email]?[parameters]

Week API URL example:

https://api.freebusy.io/beta/week/[email protected]?tz=America/New_York&date=2016-01-28

HTTP verb:

GET

Querystring Parameters (required):

1. Time zone you want the schedule represented in, IANA format

tz=America/Chicago

2. Date from which we determine the week you want, in any parsable U.S. date format

date=7-8-2015

Output:

Each busy slot has its start and end time expressed in a standard ISO 8601 but also as the number of minutes from midnight. This way the client easily perform offset calculations when rendering the week view.

{
   "weekOfYear": 28,
   "startDate": "2015-07-06T00:00:00-07:00",
   "endDate": "2015-07-12T00:00:00-07:00",
   "startTimeInMin": 480,
   "endTimeInMin": 1140,
   "days": [{
         "date": "2015-07-06T00:00:00-07:00",
         "dayOfWeekName": "Monday",
         "dayOfWeekIndex": 1,
          "startTimeInMin": 480,
          "endTimeInMin": 1140,
          "events": [{
              "startTime": "2015-07-06T07:00:00-07:00",
              "endTime": "2015-07-06T08:00:00-07:00",
              "startTimeInMin": 420,
              "endTimeInMin": 480,
              "durationInMin": 60,
              "availability": "Busy"
          }],
          "visibility": "Public"
      },
      {
          "date": "2015-07-07T00:00:00-07:00",
          "dayOfWeekName": "Tuesday",
          "dayOfWeekIndex": 2,
          "startTimeInMin": 480,
          "endTimeInMin": 1140,
          "events": [{
              "startTime": "2015-07-07T06:00:00-07:00",
              "endTime": "2015-07-07T07:00:00-07:00",
              "startTimeInMin": 360,
              "endTimeInMin": 420,
              "durationInMin": 60,
              "availability": "Busy"
          }],
          "visibility": "Public"
      },
      {
          "date": "2015-07-08T00:00:00-07:00",
          "dayOfWeekName": "Wednesday",
          "dayOfWeekIndex": 3,
          "startTimeInMin": 480,
          "endTimeInMin": 1140,
          "events": [{
              "startTime": "2015-07-08T08:00:00-07:00",
             "endTime": "2015-07-08T08:30:00-07:00",
              "startTimeInMin": 480,
              "endTimeInMin": 510,
              "durationInMin": 30,
              "availability": "Busy"
          }],
          "visibility": "Public"
      },
      {
         "date": "2015-07-09T00:00:00-07:00",
          "dayOfWeekName": "Thursday",
          "dayOfWeekIndex": 4,
          "startTimeInMin": 480,
          "endTimeInMin": 1140,
          "events": [{
              "startTime": "2015-07-09T03:30:00-07:00",
             "endTime": "2015-07-09T04:30:00-07:00",
             "startTimeInMin": 210,
              "endTimeInMin": 270,
              "durationInMin": 60,
              "availability": "Busy"
          }],
          "visibility": "Public"
      },
      {
          "date": "2015-07-10T00:00:00-07:00",
          "dayOfWeekName": "Friday",
          "dayOfWeekIndex": 5,
          "startTimeInMin": 480,
          "endTimeInMin": 1140,
         "events": [{
              "startTime": "2015-07-10T07:00:00-07:00",
              "endTime": "2015-07-10T08:00:00-07:00",
              "startTimeInMin": 420,
              "endTimeInMin": 480,
              "durationInMin": 60,
              "availability": "Busy"
          }],
          "visibility": "Public"
      },
      {
         "date": "2015-07-11T00:00:00-07:00",
          "dayOfWeekName": "Saturday",
         "dayOfWeekIndex": 6,
          "startTimeInMin": 480,
         "endTimeInMin": 1140,
          "events": [],
          "visibility": "Private"
      },
      {
         "date": "2015-07-12T00:00:00-07:00",
         "dayOfWeekName": "Sunday",
          "dayOfWeekIndex": 0,
         "startTimeInMin": 480,
      "endTimeInMin": 1140,
      "events": [],
      "visibility": "Private"
      }]
}