Querying calendar events via the Google Calendar API
Do you want to pull all meetings & events from your or any shared Google calendar via the Google calendar API in Python? This blogpost provides step-for-step instructions on how to setup authentication, request calendar events and handle the pagination token. For the full code, check the calendar-insights repository.
Setup Google Calendar API
First we need to activate the Google Calendar API for a Google cloud project of our choice. Use an existing project or create a new one: At the top of the Google Cloud Console dashboard, click on the project selection and “New Project”, enter a name e.g. “calendar-insights” and click “Create”. Then, in the Google API dashboard, click Enable APIs and services. Search for the Google Calendar API and click Enable.
Next, to enable API queries from our local computer, we need to create and download authentication credentials for that project. In the Credentials section of the API dashboard, click Create Credentials and OAuth Client ID. Select Application type “Desktop app”. Then click “Download JSON” and store the credentials file on your local PC.
⚠️ If this is the first time you are creating credentials for this project, Google will show you a dialogue to first create an OAuth consent screen. This can seem a bit daunting because there are many configuration options. Just select the “External” user type, enter an app name (e.g. calendar-insights), your email and just leave the rest empty/keep the defaults. When finished, repeat the Create Credentials step.
Basic query example with the Google Calendar API
Before querying the calendar of multiple people over long time periods, lets start with a basic query example to learn about authentication and the query parameters.
In the code below, provide the name/filepath to the downloaded OAuth credentials file from above. When running this code, your browser will open with the typical Google login screen and ask you authenticate this app. Login with the Google account of the desired Google calendar.
Not shown here, but in order to avoid the authentication step in the browser next time we run this application, we can also store the token received from the authentication and reuse it next time. See the calendar-insights github repository for the full implementation.
Now we can perform a basic query with the Calendar API for one month of our own calendar events and put them in a pandas dataframe. Each calendar event has information about its name, start & end time, attendees etc.
Querying multiple calendars and results pagination
Except your own calendar, you can only query data from calendars you are subscribed to. You can subscribe to shared calendars either manually on the Google calendar page (See the + symbol under “Other calendars”) or in code via the API as shown below.
We can now query the email ids of all calendars we are subscribed to and for which we want to query the calendar events.
Now the advanced calendar query: We loop through all subscribed calendars via their email ids and query the calendar events for a two 2-year period. The maximum amount of events we can get in a single “events.list” API request is 2500. If we want all events for long time periods, we will certainly reach that number and have to use pagination. Pagination means that the API splits up the huge amount of returned calendar events into suitable chunks. If there are more events, the Google server will send us the first page with 2500 of the results. It also indicates that there is a second page by including a “nextPageToken” in the request response. We can then perform a second query, with the same query parameters, but adding that nextPageToken. We then receive the second page of 2500 results, again with a pagination token for the next batch until no more additional results are left.
Success! The dataframe contains the calendar events of all queried calendars, now you can start with analysing meeting habits or people’s interactions! Head over to the calendar-insights repository to check out the full code implementation.
You can follow me on chrieke.com and Twitter @ chrieke
