Creating a SharePoint list item with a geolocation field
In previous article, I showed how to create a SharePoint list with a hyperlink field using the Microsoft Graph API.
The 'trick' is to use the Prefer: apiversion=2.1 header to enforce the request to be routed to the beta version of the internal SharePoint API.
For geolocation field, I will start with a different approach. Let's create a SharePoint list with a geolocation field directly in the web browser.
While you type the address of your location, the SharePoint internally calls some https://outlook.office365.com/SchedulingB2/api/v1.0/me/findmeetinglocations endpoint to get the suggestions.
When you retreive the geolocation field using the Microsoft Graph API, you will see what properties are returned for the geolocation field and what's need to be filled when creating a new geolocation field.
GET /v1.0/sites/{site_id}/lists/{list_id}/items/{item_id}/fields
The response:
{
"Title": "Project1",
"ProjectUrl": {
"Description": "Project 1 Home Site",
"Url": "https://www.project-1.com"
},
"Location": {
"address": {
"city": "Praha 10",
"countryOrRegion": "Czechia",
"postalCode": "140 00",
"state": "Capital City of Prague",
"street": "Vyskočilova 1561/4a",
"type": "Unknown"
},
"coordinates": {
"latitude": 50.0482,
"longitude": 14.4573
},
"displayName": "Microsoft",
"locationUri": "https://www.bingapis.com/api/v6/localbusinesses/YN8046x576897103687762284",
"uniqueId": "https://www.bingapis.com/api/v6/localbusinesses/YN8046x576897103687762284"
},
"CountryOrRegion": "Czechia",
"State": "Capital City of Prague",
"City": "Praha 10",
"PostalCode": "140 00",
"Street": "Vyskočilova 1561/4a",
"GeoLoc": {
"latitude": 50.0482,
"longitude": 14.4573
},
"DispName": "Microsoft",
...
}
From the response, it's clear that the geolocation field requires information about the address and coordinates. The two big unknowns are uniqueId and locationUri properties. These properties contain some Bing API endpoint, but the Bing API itself is something which is not publically documented.
You may notice that the field also contains separate columns for CountryOrRegion, State, City, PostalCode, Street, GeoLoc, and DispName. These columns are read-only and automatically populated based on the geolocation field.
Let's try to create a SharePoint list item with the same geolocation field using the Microsoft Graph API, but without uniqueId and locationUri.
POST /v1.0/sites/{site_id}/lists/{list_id}/items/{item_id}/fields
Prefer: apiversion=2.1
{
"fields": {
"Title": "Project2",
"ProjectUrl": {
"Description": "Project 2 home site",
"Url": "https://www.project2.com"
},
"Location": {
"address": {
"city": "Praha 10",
"countryOrRegion": "Czechia",
"postalCode": "140 00",
"state": "Capital City of Prague",
"street": "Vyskočilova 1561/4a",
"type": "Unknown"
},
"coordinates": {
"latitude": 50.0482,
"longitude": 14.4573
},
"displayName": "Microsoft",
"locationUri": "",
"uniqueId": ""
}
}
}
Item is created, but when you check the SharePoint list, you will see that read-only columns CountryOrRegion, State, City, PostalCode, and Street are not populated.
Even if you try to edit the item, you will see that the location field is empty.
Let's try to retrieve the geolocation field of the item created via web browser, but include the Prefer: apiversion=2.1 header in the request.
GET /v1.0/sites/{site_id}/lists/{list_id}/items/{item_id}/fields
Prefer: apiversion=2.1
The response will be:
{
"Title": "Project1",
"ProjectUrl": "https://www.project-1.com, Project 1 Home Site",
"CountryOrRegion": "Czechia",
"State": "Capital City of Prague",
"City": "Praha 10",
"PostalCode": "140 00",
"Street": "Vyskočilova 1561/4a",
"DispName": "Microsoft",
"Location": {
"displayName": "Microsoft",
"locationUri": "https://www.bingapis.com/api/v6/localbusinesses/YN8046x576897103687762284",
"uniqueId": "https://www.bingapis.com/api/v6/localbusinesses/YN8046x576897103687762284",
"Score@odata.type": "#Int64",
"Score": -20,
"EntityType": "LocalBusiness",
"LocationSource": "Bing",
"FormattedAddress": "Vyskočilova 1561/4a 140 00 Praha 10",
"Availability": "Unknown",
"IsPreviouslyUsed": false,
"Id": "https://www.bingapis.com/api/v6/localbusinesses/YN8046x576897103687762284",
"address": {
"city": "Praha 10",
"countryOrRegion": "Czechia",
"postalCode": "140 00",
"state": "Capital City of Prague",
"street": "Vyskočilova 1561/4a",
"Type": "Unknown",
"IsInferred": false
},
"coordinates": {
"latitude": 50.0482,
"longitude": 14.4573
}
},
"GeoLoc": {
"latitude": 50.0482,
"longitude": 14.4573
}
}
You can see that the Location field contain additional properties like Score, EntityType, LocationSource, FormattedAddress, Availability, IsPreviouslyUsed, and Id. Not sure about the exact purpose of these properties, but it has no effect if you try to create a new item with these properties.
Conclusion
At the moment, it's possible to create a geolocation field of a SharePoint list item using the Microsoft Graph API if you add the Prefer: apiversion=2.1 header to your request, but the read-only columns CountryOrRegion, State, City, PostalCode, and Street are not populated. It has effect on visualiazation of the geolocation field in the SharePoint list.
