Upcoming change to Event schema in the Outlook REST API beta endpoint
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.
To support multiple locations in the Event schema, we are adding:
- A
Locationsproperty as part of theEventresource - A
LocationTypeproperty to theLocationcomplex type, with an enumeration of possible locations types
This change is currently available on the https://outlook.office.com/api/beta endpoint.
Note: These are schema additions and the existing
Locationproperty that represents a single location for an event has not been removed, to allow for an easier transition. If your REST client is already usingLocation, your client doesn't break. However, be aware that in the future, theLocationproperty will be removed, and apps will need to be updated.
Here are the updated portions of the schema, with the changes highlighted.
<EntityType Name="Event" BaseType="Microsoft.OutlookServices.Item">
...
<Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
<Property Name="OriginalStart" Type="Edm.DateTimeOffset" />
<Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
<Property Name="Location" Type="Microsoft.OutlookServices.Location" />
<Property Name="Locations" Type="Collection(Microsoft.OutlookServices.Location)" />
<Property Name="Start" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
<Property Name="OriginalStart" Type="Edm.DateTimeOffset" />
<Property Name="End" Type="Microsoft.OutlookServices.DateTimeTimeZone" />
...
</EntityType>
<ComplexType Name="Location">
<Property Name="DisplayName" Type="Edm.String" />
<Property Name="LocationEmailAddress" Type="Edm.String" />
<Property Name="Address" Type="Microsoft.OutlookServices.PhysicalAddress" />
<Property Name="Coordinates" Type="Microsoft.OutlookServices.GeoCoordinates" />
<Property Name="LocationUri" Type="Edm.String" />
<Property Name="LocationType" Type="Microsoft.OutlookServices.LocationType" />
</ComplexType>
<EnumType Name="LocationType">
<Member Name="Default" Value="0" />
<Member Name="ConferenceRoom" Value="1" />
<Member Name="HomeAddress" Value="2" />
<Member Name="BusinessAddress" Value="3" />
<Member Name="GeoCoordinates" Value="4" />
<Member Name="StreetAddress" Value="5" />
<Member Name="Hotel" Value="6" />
<Member Name="Restaurant" Value="7" />
<Member Name="LocalBusiness" Value="8" />
<Member Name="PostalAddress" Value="9" />
</EnumType>
Using multiple locations and location types in the Outlook Rest API
Get events
You can use the GET /me/events API to get a collection of calendar events:
GET https://outlook.office.com/api/beta/me/events?$select=Subject,Organizer,Start,End,Locations,Location
With this schema addition, the GET /me/events command will return, for each Event, the collection of Locations.
Example of a response:
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events(Subject,Organizer,Start,End,Locations,Location)",
"value": [
{
"@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": "2017-11-28T08:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2017-11-28T09:00:00",
"TimeZone": "Pacific Standard Time"
},
"Organizer": {
"EmailAddress": {
"Name": "Adele Vance",
"Address": "adelev@contoso.onmicrosoft.com"
}
},
"Location": {
"DisplayName": "Conf Room 3; Fourth Coffee; Home Office",
"LocationType": "Default"
},
"Locations": [
{
"DisplayName": "Conf Room 3",
"LocationType": "ConferenceRoom"
},
{
"DisplayName": "Fourth Coffee",
"Address": {
"Street": "4567 Main St",
"City": "Redmond",
"State": "WA",
"CountryOrRegion": "US",
"PostalCode": "32008"
},
"Coordinates": {
"Latitude": 47.672,
"Longitude": -102.103
},
"LocationType": "LocalBusiness"
},
{
"DisplayName": "Home Office",
"LocationType": "Default"
}
]
}
]
}
Create an event with multiple locations
The following example creates a new event on the user's default calendar with multiple locations.
POST https://outlook.office.com/api/beta/me/events
Content-Type: application/json
{
"Subject": "Discuss the Event in Multiple Locations REST API",
"Start": {
"DateTime": "2017-06-06T08:00:00",
"TimeZone": "Pacific Standard Time"
},
"End": {
"DateTime": "2017-06-06T09:00:00",
"TimeZone": "Pacific Standard Time"
},
"Attendees": [
{
"EmailAddress": {
"Address": "janets@contoso.onmicrosoft.com",
"Name": "Janet Schorr"
},
"Type": "Required"
}
],
"Locations": [
{
"DisplayName": "Conf Room 3",
"LocationType": "ConferenceRoom"
},
{
"DisplayName": "Fourth Coffee",
"Address": {
"Street": "4567 Main St",
"City": "Redmond",
"State": "WA",
"CountryOrRegion": "US",
"PostalCode": "32008"
},
"Coordinates": {
"Latitude": 47.672,
"Longitude": -102.103
},
"LocationType": "LocalBusiness"
}
]
}
Update an event with multiple locations
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.
For example, the following example would add the Conf Room 2 (New York) location to the existing locations of the event created in the previous example.
PATCH https://outlook.office.com/api/beta/me/events/{event-id}
Content-Type: application/json
{
"Locations": [
{
"DisplayName": "Conf Room 3",
"LocationType": "ConferenceRoom"
},
{
"DisplayName": "Fourth Coffee",
"Address": {
"Street": "4567 Main St",
"City": "Redmond",
"State": "WA",
"CountryOrRegion": "US",
"PostalCode": "32008"
},
"Coordinates": {
"Latitude": 47.672,
"Longitude": -102.103
},
"LocationType": "LocalBusiness"
},
{
"DisplayName": "Conf Room 2 (New York)",
"LocationType": "ConferenceRoom"
}
]
}
Behavior with Location property
Apps should update to use the Locations property. However, if an app continues to use the Location property, the property will behave in the following ways:
Read
When reading the Location property, the value will include a Location entity with just the DisplayName and LocationType properties. The DisplayName property will be a semi-colon delimited list of the display names of each location in the Locations property, and the LocationType will be Default.
Write
If an app updates the Location property via POST or PATCH, the Locations property will be updated to have the same Location entity as the one and only location in the collection. So, if an event already has multiple locations, and an app updates the Location property, all existing locations will be removed from the Locations property and replaced with the single location set in the Location property.