office365office365apioutlook-restapioffice365-restapi

How should start and end timezone be handled in OData parameters in O365 Calendar REST API v2.0?


What I'm trying to achieve

I want to get all events in a user's calendar, sometimes within a specific window between two instants in time, sometimes just all. These events have to be ordered on event start as an instant in time.

The problem I'm facing

I'm having some issues with using the OData v4 $filter and $orderby query parameters for filtering and ordering by the event's Start and End. The problem is that since v2.0 of the API, these attributes are objects consisting of a DateTime and a TimeZone and that the TimeZone should be taken into account when filtering/ordering by the DateTime.

This snippet is taken from the official docs:

{
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGI28tEyDAAA=')",
    "@odata.etag": "W/\"nfZyf7VcrEKLNoU37KWlkQAA/LpDWw==\"",
    "Id": "AAMkAGI28tEyDAAA=",
    "Subject": "Scrum",
    "Start": {
        "DateTime": "2015-11-02T17:00:00",
        "TimeZone": "Pacific Standard Time"
    },
    "End": {
        "DateTime": "2015-11-02T17:30:00",
        "TimeZone": "Pacific Standard Time"
    },
    ...
}

I could filter on Start/DateTime and End/DateTime, but that doesn't take timezone offsets into account. Same goes for ordering by Start/DateTime:

https://outlook.office365.com/api/v2.0/users/user@example.org/events/?$filter=End/DateTime%20gt%202016-12-11T00:00:00&$orderby=Start/DateTime

Trying to order by just Start results in an error, which tells me I can't order on a non-primitive attribute.

The timezones I receive in the responses all seem to be UTC, regardless which timezone I specify when creating the event. However, the docs show 'Pacific Stardard Time', so I probably can't assume all events are always converted to UTC.

Why this problem didn't exist in the v1.0 API

In v1.0 of the API, Start and End were still of the (primitive) datetimeoffset, and StartTimeZone and EndTimeZone were separate attributes, so the problem didn't exist by then. Start and End contained an offset, so I could filter on these attributes and order by them while just ignoring the StartTimeZone and EndTimeZone attributes.

Using /calendarview instead of /events

I'm aware of the existence of the /calendarview endpoint, which allows me to specify a window to retrieve events for. However, using this endpoint also implies that I receive all occurences (in which I'm not interested) of events instead of single events and series masters. That's one of the reasons why I'd prefer to use the regular /events endpoint.


Solution

  • You can pass the prefer time zone header to get the response in your desired time zone

    Prefer: outlook.timezone="Eastern Standard Time"