Azure Maps as an Event Grid source
This article provides the properties and schema for Azure Maps events. For an introduction to event schemas, see Azure Event Grid event schema. It also gives you a list of quick starts and tutorials to use Azure Maps as an event source.
Available event types
An Azure Maps account emits the following event types:
Event type | Description |
---|---|
Microsoft.Maps.GeofenceEntered | Raised when coordinates received have moved from outside of a given geofence to within |
Microsoft.Maps.GeofenceExited | Raised when coordinates received have moved from within a given geofence to outside |
Microsoft.Maps.GeofenceResult | Raised every time a geofencing query returns a result, regardless of the state |
Example events
The following example shows the schema of a GeofenceEntered event
{
"id":"7f8446e2-1ac7-4234-8425-303726ea3981",
"source":"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Maps/accounts/{accountName}",
"subject":"/spatial/geofence/udid/{udid}/id/{eventId}",
"data":{
"geometries":[
{
"deviceId":"device_1",
"udId":"1a13b444-4acf-32ab-ce4e-9ca4af20b169",
"geometryId":"2",
"distance":-999.0,
"nearestLat":47.618786,
"nearestLon":-122.132151
}
],
"expiredGeofenceGeometryId":[
],
"invalidPeriodGeofenceGeometryId":[
]
},
"type":"Microsoft.Maps.GeofenceEntered",
"time":"2018-11-08T00:54:17.6408601Z",
"specversion":"1.0"
}
The following example show schema for GeofenceResult
{
"id":"451675de-a67d-4929-876c-5c2bf0b2c000",
"source":"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Maps/accounts/{accountName}",
"subject":"/spatial/geofence/udid/{udid}/id/{eventId}",
"data":{
"geometries":[
{
"deviceId":"device_1",
"udId":"1a13b444-4acf-32ab-ce4e-9ca4af20b169",
"geometryId":"1",
"distance":999.0,
"nearestLat":47.609833,
"nearestLon":-122.148274
},
{
"deviceId":"device_1",
"udId":"1a13b444-4acf-32ab-ce4e-9ca4af20b169",
"geometryId":"2",
"distance":999.0,
"nearestLat":47.621954,
"nearestLon":-122.131841
}
],
"expiredGeofenceGeometryId":[
],
"invalidPeriodGeofenceGeometryId":[
]
},
"type":"Microsoft.Maps.GeofenceResult",
"time":"2018-11-08T00:52:08.0954283Z",
"specversion":"1.0"
}
Event properties
An event has the following top-level data:
Property | Type | Description |
---|---|---|
source |
string | Full resource path to the event source. This field isn't writeable. Event Grid provides this value. |
subject |
string | Publisher-defined path to the event subject. |
type |
string | One of the registered event types for this event source. |
time |
string | The time the event is generated based on the provider's UTC time. |
id |
string | Unique identifier for the event. |
data |
object | Geofencing event data. |
specversion |
string | CloudEvents schema specification version. |
The data object has the following properties:
Property | Type | Description |
---|---|---|
apiCategory |
string | API category of the event. |
apiName |
string | API name of the event. |
issues |
object | Lists issues occurred during processing. If any issues are returned, then there will be no geometries returned with the response. |
responseCode |
number | HTTP response code |
geometries |
object | Lists the fence geometries that contain the coordinate position or overlap the searchBuffer around the position. |
The error object is returned when an error occurs in the Maps API. The error object has the following properties:
Property | Type | Description |
---|---|---|
error |
ErrorDetails | This object is returned when an error occurs in the Maps API |
The ErrorDetails object is returned when an error occurs in the Maps API. The ErrorDetails or object has the following properties:
Property | Type | Description |
---|---|---|
code |
string | The HTTP status code. |
message |
string | If available, a human readable description of the error. |
innererror |
InnerError | If available, an object containing service-specific information about the error. |
The InnerError is an object containing service-specific information about the error. The InnerError object has the following properties:
Property | Type | Description |
---|---|---|
code |
string | The error message. |
The geometries object lists geometry IDs of the geofences that have expired relative to the user time in the request. The geometries object has geometry items with the following properties:
Property | Type | Description |
---|---|---|
deviceid |
string | ID of device. |
distance |
string | Distance from the coordinate to the closest border of the geofence. Positive means the coordinate is outside of the geofence. If the coordinate is outside of the geofence, but more than the value of searchBuffer away from the closest geofence border, then the value is 999. Negative means the coordinate is inside of the geofence. If the coordinate is inside the polygon, but more than the value of searchBuffer away from the closest geofencing border, then the value is -999. A value of 999 means that there's great confidence the coordinate is well outside the geofence. A value of -999 means that there's great confidence the coordinate is well within the geofence. |
geometryid |
string | The unique ID identifies the geofence geometry. |
nearestlat |
number | Latitude of the nearest point of the geometry. |
nearestlon |
number | Longitude of the nearest point of the geometry. |
udId |
string | The unique ID returned from user upload service when uploading a geofence. Won't be included in geofencing post API. |
The data object has the following properties:
Property | Type | Description |
---|---|---|
expiredGeofenceGeometryId |
string[] | Lists of the geometry ID of the geofence that is expired relative to the user time in the request. |
geometries |
geometries[] | Lists the fence geometries that contain the coordinate position or overlap the searchBuffer around the position. |
invalidPeriodGeofenceGeometryId |
string[] | Lists of the geometry ID of the geofence that is in invalid period relative to the user time in the request. |
isEventPublished |
boolean | True if at least one event is published to the Azure Maps event subscriber, false if no event is published to the Azure Maps event subscriber. |
Tutorials and how-tos
Title | Description |
---|---|
React to Azure Maps events by using Event Grid | Overview of integrating Azure Maps with Event Grid. |
Tutorial: Set up a geofence | This tutorial walks you through the basics steps to set up geofence by using Azure Maps. You use Azure Event Grid to stream the geofence results and set up a notification based on the geofence results. |
Next steps
- For an introduction to Azure Event Grid, see What is Event Grid?
- For more information about creating an Azure Event Grid subscription, see Event Grid subscription schema.