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.

Get Started

  1. Watch the demo segment in the video below

  2. Read the short documentation

  3. Give us feedback (it's a work in progress)



Video index:

  • [00:15] Tell us about yourself and about FreeBusy.io
  • [02:34] Provider-independent free and busy information for anyone
  • [03:12] How is adoption going so far?
  • [03:29] Combination of multiple calendars
  • [04:51] Can I add an iCal calendar?
  • [05:22] Let's sign me up!
  • [07:15] Am I giving you my actual email password here?
  • [09:44] The value of 3rd party authentication
  • [18:07] Let's take a look at the API
  • [21:37] How would a developer give feedback to your team?
  • [29:34] Is the calendar view interactive so I can choose meeting times?


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
    2. tz=America/Chicago
  2. Date from which we determine the week you want, in any parsable U.S. date format
    3. 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"
      }]
}