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.
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.
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.
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.
You can pass the prefer time zone header to get the response in your desired time zone
Prefer: outlook.timezone="Eastern Standard Time"