4

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.

P44T
  • 1,109
  • 12
  • 21
  • There are two ampersands instead of %27 (single quotes) surrounding the datetime you are filtering by. Checking the documentation, it should look like this: /api/v2.0/users/user@example.org/events/?$filter=End/DateTime%20gt%20%272016-12-11T00:00:00%27&$orderby=Start/DateTime – zerohero Dec 12 '16 at 12:52
  • The first ampersand is a typo, so I removed it now, thanks. The second one indicates the next query parameter, so it needs to be there. The docs show there shouldn't be quotes around a timestamp: https://msdn.microsoft.com/en-us/office/office365/api/complex-types-for-mail-contacts-calendar#Filter. – P44T Dec 12 '16 at 13:01
  • thanks for the correction, however here is what this https://msdn.microsoft.com/en-us/office/office365/api/complex-types-for-mail-contacts-calendar#OdataQueryParams documentation says as an example, api/v2.0/me/events?$filter=Start/DateTime%20ge%20%272016-04-01T08:00%27 .%27 is a single quote. However I see many examples without, so I assume you are correct – zerohero Dec 12 '16 at 13:26
  • Uhm, this is going to sound stupid, but could you try $orderby=Start\DateTime instead? (note the forward slash is now a backslash) – zerohero Dec 12 '16 at 13:38
  • To be more clear, my problem is not that filtering on `Start/DateTime` does not work, but that the timezone is not taken into account, because afaik every event can have a different `Start/TimeZone`. The DateTime doesn't have a real meaning without its TimeZone. – P44T Dec 12 '16 at 13:43
  • Sorry, focused on the wrong issue then. $orderby=Start/DateTime,Start/TimeZone (or TimeZone, then DateTime) – zerohero Dec 12 '16 at 13:45

1 Answers1

1

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

Prefer: outlook.timezone="Eastern Standard Time"

Yogesh
  • 2,198
  • 1
  • 19
  • 28
  • Thanks a lot for this answer! This feature is unfortunately not documented in the official API docs. That's why I didn't find it earlier. It's documented in this Microsoft blog, however: https://blogs.msdn.microsoft.com/exchangedev/2015/10/14/outlook-rest-api-changes-to-beta-endpoint-part-ii/ – P44T Feb 12 '17 at 22:04