{"id":1583,"date":"2017-06-01T15:26:47","date_gmt":"2017-06-01T15:26:47","guid":{"rendered":"https:\/\/developer.microsoft.com\/en-us\/office\/blogs\/?p=1583"},"modified":"2017-06-01T15:26:47","modified_gmt":"2017-06-01T15:26:47","slug":"upcoming-change-to-event-schema-in-the-outlook-rest-api-beta-endpoint","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/upcoming-change-to-event-schema-in-the-outlook-rest-api-beta-endpoint\/","title":{"rendered":"Upcoming change to Event schema in the Outlook REST API beta endpoint"},"content":{"rendered":"<p>We wanted to give you a heads-up on upcoming changes to how locations are exposed for events in the Outlook REST API. Outlook recently introduced the option to use multiple locations to schedule meetings and appointments. The feature is designed for meetings scheduled for persons and teams spanning different regions, for example, some people attending in a conference room in Seattle, another person joining from a coffee shop in Paris, and others from the New York office, with all the locations connected via Skype for Business.<\/p>\n<p>To support multiple locations in the <code>Event<\/code> schema, we are adding:<\/p>\n<ul>\n<li>A <code>Locations<\/code> property as part of the <code>Event<\/code> resource<\/li>\n<li>A <code>LocationType<\/code> property to the <code>Location<\/code> complex type, with an enumeration of possible locations types<\/li>\n<\/ul>\n<p>This change is currently available on the <code>https:\/\/outlook.office.com\/api\/beta<\/code> endpoint.<\/p>\n<blockquote><p><strong>Note:<\/strong> These are schema additions and the existing <code>Location<\/code> property that represents a single location for an event has not been removed, to allow for an easier transition. If your REST client is already using <code>Location<\/code>, your client doesn&#8217;t break. However, be aware that in the future, the <code>Location<\/code> property will be removed, and apps will need to be updated.<\/p><\/blockquote>\n<p>Here are the updated portions of the schema, with the changes highlighted.<\/p>\n<pre><code>&lt;EntityType Name=\"Event\" BaseType=\"Microsoft.OutlookServices.Item\"&gt;\n    ...\n    &lt;Property Name=\"Start\" Type=\"Microsoft.OutlookServices.DateTimeTimeZone\" \/&gt;\n    &lt;Property Name=\"OriginalStart\" Type=\"Edm.DateTimeOffset\" \/&gt;\n    &lt;Property Name=\"End\" Type=\"Microsoft.OutlookServices.DateTimeTimeZone\" \/&gt;\n    &lt;Property Name=\"Location\" Type=\"Microsoft.OutlookServices.Location\" \/&gt;\n    &lt;Property Name=\"Locations\" Type=\"Collection(Microsoft.OutlookServices.Location)\" \/&gt;\n    &lt;Property Name=\"Start\" Type=\"Microsoft.OutlookServices.DateTimeTimeZone\" \/&gt;\n    &lt;Property Name=\"OriginalStart\" Type=\"Edm.DateTimeOffset\" \/&gt;\n    &lt;Property Name=\"End\" Type=\"Microsoft.OutlookServices.DateTimeTimeZone\" \/&gt;\n    ...\n&lt;\/EntityType&gt;\n\n&lt;ComplexType Name=\"Location\"&gt;\n    &lt;Property Name=\"DisplayName\" Type=\"Edm.String\" \/&gt;\n    &lt;Property Name=\"LocationEmailAddress\" Type=\"Edm.String\" \/&gt;\n    &lt;Property Name=\"Address\" Type=\"Microsoft.OutlookServices.PhysicalAddress\" \/&gt;\n    &lt;Property Name=\"Coordinates\" Type=\"Microsoft.OutlookServices.GeoCoordinates\" \/&gt;\n    &lt;Property Name=\"LocationUri\" Type=\"Edm.String\" \/&gt;\n    &lt;Property Name=\"LocationType\" Type=\"Microsoft.OutlookServices.LocationType\" \/&gt;\n&lt;\/ComplexType&gt;\n\n&lt;EnumType Name=\"LocationType\"&gt;\n    &lt;Member Name=\"Default\" Value=\"0\" \/&gt;\n    &lt;Member Name=\"ConferenceRoom\" Value=\"1\" \/&gt;\n    &lt;Member Name=\"HomeAddress\" Value=\"2\" \/&gt;\n    &lt;Member Name=\"BusinessAddress\" Value=\"3\" \/&gt;\n    &lt;Member Name=\"GeoCoordinates\" Value=\"4\" \/&gt;\n    &lt;Member Name=\"StreetAddress\" Value=\"5\" \/&gt;\n    &lt;Member Name=\"Hotel\" Value=\"6\" \/&gt;\n    &lt;Member Name=\"Restaurant\" Value=\"7\" \/&gt;\n    &lt;Member Name=\"LocalBusiness\" Value=\"8\" \/&gt;\n    &lt;Member Name=\"PostalAddress\" Value=\"9\" \/&gt;\n&lt;\/EnumType&gt;\n<\/code><\/pre>\n<h2>Using multiple locations and location types in the Outlook Rest API<\/h2>\n<h3>Get events<\/h3>\n<p>You can use the GET \/me\/events API to get a collection of calendar events:<\/p>\n<pre><code>GET https:\/\/outlook.office.com\/api\/beta\/me\/events?$select=Subject,Organizer,Start,End,Locations,Location<\/code><\/pre>\n<p>With this schema addition, the <code>GET \/me\/events<\/code> command will return, for each <code>Event<\/code>, the collection of <code>Locations<\/code>.<\/p>\n<p>Example of a response:<\/p>\n<pre><code>{\n  \"@odata.context\": \"https:\/\/outlook.office.com\/api\/beta\/$metadata#Me\/Events(Subject,Organizer,Start,End,Locations,Location)\",\n  \"value\": [\n    {\n      \"@odata.id\": \"https:\/\/outlook.office.com\/api\/beta\/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')\/Events('AAMkAGI28tEyDAAA=')\",\n      \"@odata.etag\": \"W\/\\\"nfZyf7VcrEKLNoU37KWlkQAA\/LpDWw==\\\"\",\n      \"Id\": \"AAMkAGI28tEyDAAA=\",\n      \"Subject\": \"Scrum\",\n      \"Start\": {\n        \"DateTime\": \"2017-11-28T08:00:00\",\n        \"TimeZone\": \"Pacific Standard Time\"\n      },\n      \"End\": {\n        \"DateTime\": \"2017-11-28T09:00:00\",\n        \"TimeZone\": \"Pacific Standard Time\"\n      },\n      \"Organizer\": {\n        \"EmailAddress\": {\n          \"Name\": \"Adele Vance\",\n          \"Address\": \"adelev@contoso.onmicrosoft.com\"\n        }\n      },\n      \"Location\": {\n        \"DisplayName\": \"Conf Room 3; Fourth Coffee; Home Office\",\n        \"LocationType\": \"Default\"\n      },\n      \"Locations\": [\n        {\n          \"DisplayName\": \"Conf Room 3\",\n          \"LocationType\": \"ConferenceRoom\"\n        },\n        {\n          \"DisplayName\": \"Fourth Coffee\",\n          \"Address\": {\n            \"Street\": \"4567 Main St\",\n            \"City\": \"Redmond\",\n            \"State\": \"WA\",\n            \"CountryOrRegion\": \"US\",\n            \"PostalCode\": \"32008\"\n          },\n          \"Coordinates\": {\n            \"Latitude\": 47.672,\n            \"Longitude\": -102.103\n          },\n          \"LocationType\": \"LocalBusiness\"\n        },\n        {\n          \"DisplayName\": \"Home Office\",\n          \"LocationType\": \"Default\"\n        }\n      ]\n    }\n  ]\n}\n<\/code><\/pre>\n<h3>Create an event with multiple locations<\/h3>\n<p>The following example creates a new event on the user&#8217;s default calendar with multiple locations.<\/p>\n<pre><code>POST https:\/\/outlook.office.com\/api\/beta\/me\/events\nContent-Type: application\/json\n\n{\n  \"Subject\": \"Discuss the Event in Multiple Locations REST API\",\n  \"Start\": {\n    \"DateTime\": \"2017-06-06T08:00:00\",\n    \"TimeZone\": \"Pacific Standard Time\"\n  },\n  \"End\": {\n    \"DateTime\": \"2017-06-06T09:00:00\",\n    \"TimeZone\": \"Pacific Standard Time\"\n  },\n  \"Attendees\": [\n    {\n      \"EmailAddress\": {\n        \"Address\": \"janets@contoso.onmicrosoft.com\",\n        \"Name\": \"Janet Schorr\"\n      },\n      \"Type\": \"Required\"\n    }\n  ],\n  \"Locations\": [\n    {\n      \"DisplayName\": \"Conf Room 3\",\n      \"LocationType\": \"ConferenceRoom\"\n    },\n    {\n      \"DisplayName\": \"Fourth Coffee\",\n      \"Address\": {\n        \"Street\": \"4567 Main St\",\n        \"City\": \"Redmond\",\n        \"State\": \"WA\",\n        \"CountryOrRegion\": \"US\",\n        \"PostalCode\": \"32008\"\n      },\n      \"Coordinates\": {\n        \"Latitude\": 47.672,\n        \"Longitude\": -102.103\n      },\n      \"LocationType\": \"LocalBusiness\"\n    }\n  ]\n}\n<\/code><\/pre>\n<h3>Update an event with multiple locations<\/h3>\n<p>To update locations of an event, apps include the Locations property in the PATCH payload. The existing value of the Locations property is overwritten, so in order to add a location to an existing event, apps should get the current value of the Locations property, then add the new location, and PATCH the resulting value.<\/p>\n<p>For example, the following example would add the <strong>Conf Room 2 (New York)<\/strong> location to the existing locations of the event created in the previous example.<\/p>\n<pre><code>PATCH https:\/\/outlook.office.com\/api\/beta\/me\/events\/{event-id}\nContent-Type: application\/json\n\n{\n  \"Locations\": [\n    {\n      \"DisplayName\": \"Conf Room 3\",\n      \"LocationType\": \"ConferenceRoom\"\n    },\n    {\n      \"DisplayName\": \"Fourth Coffee\",\n      \"Address\": {\n        \"Street\": \"4567 Main St\",\n        \"City\": \"Redmond\",\n        \"State\": \"WA\",\n        \"CountryOrRegion\": \"US\",\n        \"PostalCode\": \"32008\"\n      },\n      \"Coordinates\": {\n        \"Latitude\": 47.672,\n        \"Longitude\": -102.103\n      },\n      \"LocationType\": \"LocalBusiness\"\n    },\n    {\n      \"DisplayName\": \"Conf Room 2 (New York)\",\n      \"LocationType\": \"ConferenceRoom\"\n    }\n  ]\n}\n<\/code><\/pre>\n<h3>Behavior with Location property<\/h3>\n<p>Apps should update to use the <code>Locations<\/code> property. However, if an app continues to use the <code>Location<\/code> property, the property will behave in the following ways:<\/p>\n<h4>Read<\/h4>\n<p>When reading the <code>Location<\/code> property, the value will include a <code>Location<\/code> entity with just the <code>DisplayName<\/code> and <code>LocationType<\/code> properties. The <code>DisplayName<\/code> property will be a semi-colon delimited list of the display names of each location in the <code>Locations<\/code> property, and the <code>LocationType<\/code> will be <code>Default<\/code>.<\/p>\n<h4>Write<\/h4>\n<p>If an app updates the <code>Location<\/code> property via POST or PATCH, the <code>Locations<\/code> property will be updated to have the same <code>Location<\/code> entity as the one and only location in the collection. So, if an event already has multiple locations, and an app updates the <code>Location<\/code> property, all existing locations will be removed from the <code>Locations<\/code> property and replaced with the single location set in the <code>Location<\/code> property.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>We wanted to give you a heads-up on upcoming changes to how locations are exposed for events in the Outlook REST API. Outlook recently introduced the option to use multiple locations to schedule meetings and appointments.<\/p>\n","protected":false},"author":69108,"featured_media":25159,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[12],"class_list":["post-1583","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-outlook"],"acf":[],"blog_post_summary":"<p>We wanted to give you a heads-up on upcoming changes to how locations are exposed for events in the Outlook REST API. Outlook recently introduced the option to use multiple locations to schedule meetings and appointments.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1583","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69108"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=1583"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/1583\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/25159"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=1583"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=1583"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=1583"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}