Kloudless Blog

Kloudless Unified APIs enable you to code once and integrate many

Calendaring systems such as Google and Outlook Calendar describe recurring events via recurrence rules that indicate the frequency and duration of the series of events, along with any other special rules. Check out our past blog post here for more information on recurring events and their format in the Kloudless API.

The blog post linked above briefly describes how to update an individual event in a series, or the entire series. End-users can similarly update recurring events via their calendar app’s web interface. Apps that connect to a user’s calendar commonly need to then sync this activity to their database to maintain an up-to-date representation of the user’s calendar, or otherwise react to these updates to the user’s events. This is straightforward for calendar activity that describes new, updated, or deleted events, but how should apps react to updates to entire series of events? In this post, we’ll dive into steps apps can take to process activity related to series of events in a Google Calendar account accessible via the Kloudless API.

New recurring events

Apps can track new activity in users’ calendars via the Kloudless Activity Stream (Events API). Under the hood, Kloudless uses the appropriate calendaring service’s API endpoints to track changes to a user’s calendar account, such as Google’s sync endpoints or Outlook’s. To begin, query the /events endpoint and store the cursor returned. This cursor can be used in future requests to this endpoint to retrieve new activity beyond this point in time.

Let’s explore how a newly created recurring series of events appears via this API endpoint. The screenshot below shows a user creating a new recurring calendar event that occurs every weekday, from 1:00pm to 2:00pm U.S. Pacific Time, beginning on April 2, 2019.

Here is the response from the API indicating this change:

The metadata attribute above describes a calendar event using the Kloudless unified data model representation of a calendar event (docs). Apps can also obtain the raw Google Calendar event information by setting the X-Kloudless-Raw-Data header to true (docs). The most important attribute above is the recurrence rule, described in the RFC 5545 format. This lets our app know that this object actually represents the master event in a series of calendar events rather than just a solo event, as shown in the screenshot below.

Apps can update their internal representation of a user’s calendar events in two ways:

  • The first approach is to parse the RRULE recurrence data to accurately replicate the calendar events within a developer’s application. Kloudless plans to unify the recurrence data format to simplify this process across Google, Outlook, CalDAV, and other systems.
  • The second approach is to periodically list all upcoming events in a calendar account (docs) to be aware of instances of recurring events to sync over. No calendar’s activity stream provides information on individual events that are updated as a part of a series as it would mean an infinite stream of activity—the series in the example above never ends! Therefore, the activity stream only returns a single object that describes the series of events.

Updates to recurring series

Users can easily update a series of recurring events via their calendar application’s web interface. Updates to individual events in a series are treated the same as an update to any other individual event, implicitly indicating that that event is no longer part of the series since it now contains no recurrence rule or pointer to a series master event.

However, users can also choose to update all following events in a series as well. The screenshot below shows the confirmation box that Google Calendar displays to a user who attempts to update a future event to begin an hour later at 2:00pm instead.

In this case, Google Calendar somehow needs to indicate that the past series ends at a specific point in time, and events beyond that time have a new recurrence pattern. Google Calendar establishes this by publishing two changes in the activity stream. The first describes the update to the existing series, terminating it right before the new recurrence begins. The second describes the new series moving forward. Check out the response below from a request to the activity stream endpoint using the cursor obtained from the response to the previous request:

In the response above, the first object shows that the original series master event’s recurrence rule now only applies until 20190405T065959Z (prior to midnight, April 6, 2019 PST). Notice that the calendar event’s ID matches that of the original event in the first code snippet above.

The second object represents a new series master event beginning on 2019-04-05T21:00:00Z (April 5, 2:00pm PST). It describes the change shown in the screenshot below, where the right-most column represents April 5.


Deleting series of events beyond a point in time also effectively updates the series of events to add in an UNTIL parameter in the recurrence rule. The screenshot below shows a user deleting all events after April 10 in the new series created above.

This results in the recurrence rule transforming to RRULE:FREQ=WEEKLY;UNTIL=20190410T065959Z;BYDAY=MO,TU,WE,TH,FR, indicating it terminates on April 10, 2019, immediately prior to midnight U.S. Pacific Time.


As shown above, maintaining an up-to-date representation on series of recurring events requires

  • monitoring any changes to the series or individual events in the series; and
  • either parsing series masters’ recurrence rules or periodically retrieving all future instances of events, such as requesting the upcoming month of calendar events every hour.

Check out the Kloudless Calendar API for more information on tracking these changes across any users’ calendar account.


Share this article:

Let’s get started. Start building for free today.