Set the timezone used for the events in Outlook and Microsoft Graph REST APIs

When you’ve been working for a while like me, you know that when a developer has to work with dates, he faces problems with timezones.

Outlook REST API allows you to get the events for a user by calling the following URL :

GET https://outlook.office365.com/api/v2.0/Me/Events

In the version 2.0 of the API and as you can see in the JSON response below for an event (the response shown here was truncated for brevity), the Start and End items contain two distinct properties for the date and timezone.

By default, all dates and times returned by the server are based on the UTC timezone.

{
  Attendees = (),
  Body = { ... },
  BodyPreview = "...",
  Categories = (),
  ChangeKey = "...",
  CreatedDateTime = "2015-12-02T16:21:57.91403Z";
  End = {
    DateTime = "2012-02-09T19:00:00.0000000",
    TimeZone = "UTC"
  },
  HasAttachments = false,
  Id = "...",
  Importance = "Normal",
  IsAllDay = false,
  IsCancelled = false,
  IsOrganizer = true,
  IsReminderOn = false,
  LastModifiedDateTime = "2015-12-02T16:21:58.7734204Z";
  Location = { ... },
  Organizer = { ... },
  OriginalEndTimeZone = "Pacific Standard Time",
  OriginalStartTimeZone = "Pacific Standard Time",
  Recurrence = { ... },
  ReminderMinutesBeforeStart = 0,
  ResponseRequested = true,
  ResponseStatus = { ... },
  Sensitivity = "Normal",
  SeriesMasterId = <null>,
  ShowAs = "Tentative",
  Start = {
    DateTime = "2012-02-09T18:00:00.0000000",
    TimeZone = "UTC"
  },
  Subject = "...",
  Type = "SeriesMaster"
  WebLink = "...",
  iCalUId = "..."
}

It’s now easier to know what timezone is used for the dates and times. But that’s not all.

If you want the server automatically convert the dates and times of the events into a different timezone, you are able to do so and it’s very easy.

You just have to specify a HTTP header like in the example below to change the timezone. The server will then use this new parameter to return the dates and times in the desired timezone.

Prefer: outlook.timezone="Central Standard Time"

Specifying this HTTP header and calling the previously mentioned URL, you will retrieve a new JSON response like this one :

{
  Attendees = (),
  Body = { ... },
  BodyPreview = "...",
  Categories = (),
  ChangeKey = "...",
  CreatedDateTime = "2015-12-02T16:21:57.91403Z";
  End = {
    DateTime = "2012-02-09T13:00:00.0000000",
    TimeZone = "Central Standard Time"
  },
  HasAttachments = false,
  Id = "...",
  Importance = "Normal",
  IsAllDay = false,
  IsCancelled = false,
  IsOrganizer = true,
  IsReminderOn = false,
  LastModifiedDateTime = "2015-12-02T16:21:58.7734204Z";
  Location = { ... },
  Organizer = { ... },
  OriginalEndTimeZone = "Pacific Standard Time",
  OriginalStartTimeZone = "Pacific Standard Time",
  Recurrence = { ... },
  ReminderMinutesBeforeStart = 0,
  ResponseRequested = true,
  ResponseStatus = { ... },
  Sensitivity = "Normal",
  SeriesMasterId = <null>,
  ShowAs = "Tentative",
  Start = {
    DateTime = "2012-02-09T12:00:00.0000000",
    TimeZone = "Central Standard Time"
  },
  Subject = "...",
  Type = "SeriesMaster"
  WebLink = "...",
  iCalUId = "..."
}

If you want more information about the names of supported timezones, you can find a list on the official documentation on MSDN.

It’s also good to know that even if it’s not mentioned (for now) on the official documentation, this HTTP header also works with Microsoft Graph.

4 thoughts on “Set the timezone used for the events in Outlook and Microsoft Graph REST APIs

  1. Fenoglio

    Bonjour Stephane,
    malheureusement ne fonctionne pas !

    J’envoie une requête (via MSAL en C#) dont le corps est le suivant :
    {
    “subject”: “My event”,
    “start”: {
    “dateTime”: “2019-12-04T10:08:12.532Z”,
    “timeZone”: “Romance Standard Time”
    },
    “end”: {
    “dateTime”: “2019-12-04T10:38:12.532Z”,
    “timeZone”: “Romance Standard Time”
    }
    }

    et la réponse est :
    {
    “@odata.context”: “https://graph.microsoft.com/v1.0/$metadata#users(‘c2c5a21b-f361-4523-aff3-893a224aaf16’)/events/$entity”,
    “@odata.etag”: “W/\”gzuupM+d1UaINEUv/wwyVgABFfg47g==\””,
    “id”: “AAMkAGJiOTIwODU2LWQxMmUtNGYwMC05MGI2LWUwMzQwYjI5YmEwMQBGAAAAAACyghcXOFWETobn9EDOccuGBwCDO66kz53VRog0RS–DDJWAAAAAAENAACDO66kz53VRog0RS–DDJWAAEWNEB5AAA=”,
    “createdDateTime”: “2019-12-04T16:11:03.332629Z”,
    “lastModifiedDateTime”: “2019-12-04T16:11:03.3913704Z”,
    “changeKey”: “gzuupM+d1UaINEUv/wwyVgABFfg47g==”,
    “categories”: [],
    “originalStartTimeZone”: “UTC”,
    “originalEndTimeZone”: “UTC”,
    “iCalUId”: “040000008200E00074C5B7101A82E00800000000B72D1B6DBDAAD501000000000000000010000000CE8B1C9E09E4E7418EFA5A274ADD0D2D”,
    “reminderMinutesBeforeStart”: 15,
    “isReminderOn”: true,
    “hasAttachments”: false,
    “subject”: “My event”,
    “bodyPreview”: “”,
    “importance”: “normal”,
    “sensitivity”: “normal”,
    “isAllDay”: false,
    “isCancelled”: false,
    “isOrganizer”: true,
    “responseRequested”: true,
    “seriesMasterId”: null,
    “showAs”: “busy”,
    “type”: “singleInstance”,
    “webLink”: “https://outlook.office365.com/owa/?itemid=AAMkAGJiOTIwODU2LWQxMmUtNGYwMC05MGI2LWUwMzQwYjI5YmEwMQBGAAAAAACyghcXOFWETobn9EDOccuGBwCDO66kz53VRog0RS%2F%2FDDJWAAAAAAENAACDO66kz53VRog0RS%2F%2FDDJWAAEWNEB5AAA%3D&exvsurl=1&path=/calendar/item”,
    “onlineMeetingUrl”: null,
    “recurrence”: null,
    “responseStatus”: {
    “response”: “organizer”,
    “time”: “0001-01-01T00:00:00Z”
    },
    “body”: {
    “contentType”: “text”,
    “content”: “”
    },
    “start”: {
    “dateTime”: “2019-12-04T10:08:12.5320000”,
    “timeZone”: “UTC”
    },
    “end”: {
    “dateTime”: “2019-12-04T10:38:12.5320000”,
    “timeZone”: “UTC”
    },
    “location”: {
    “displayName”: “”,
    “locationType”: “default”,
    “uniqueIdType”: “unknown”,
    “address”: {},
    “coordinates”: {}
    },
    “locations”: [],
    “attendees”: [],
    “organizer”: {
    “emailAddress”: {
    “name”: “Fenoglio, Nomi”,
    “address”: “nomi.fenoglio@arcelormittal.com”
    }
    }
    }

    Toutes les dates sont au format UTC et évidemment il y a donc un décalage entre l’heure souhaitée et l’heure enregistrée !

    Le soucis viendrait t-il du serveur ?
    Merci

    Like

    Reply
    1. Stéphane Cordonnier (@s_cordonnier) Post author

      Bonjour,

      C’est probablement parce qu’il manque l’en-tête HTTP “Prefer: outlook.timezone” dans la requête afin que le serveur puisse renvoyer les dates dans le bon fuseau horaire.

      C’est ce qui est indiqué dans la documentation officielle : “Use this to specify the time zone for start and end times in the response. If not specified, those time values are returned in UTC.”

      Like

      Reply
      1. fenoglio

        Hélas, j’ai bien l’entête setté dans mon prgromme :
        request.Content.Headers.Add(“Prefer”, “outlook.timezone=\”” + timeZone + “\””);la variable timeZone étant mise à Romance …

        Like

        Reply
        1. fenoglio

          Erreur trouvée :
          dans mon programme, je passé le champe datetime formaté via yyyy-MM-ddTHH.mm.ssZ .
          Hors le caractére ‘Z’ indique une date au format UTC. Du coup l’API GRaph se moquait oyalement de l’entête.

          Like

          Reply

Leave a Reply to Fenoglio Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.