Overview of steps
1. Add geofences around areas of interest and store them in a geofence collection resource.
2. Start tracking your target devices and store the device location history in a tracker resource.
3. Link your tracker resource to your geofence collection resource so that device location updates are automatically evaluated against all your geofences.
4. You can evaluate device positions directly against your geofence collection resources if you don’t want to use Amazon Location Trackers to keep your devices’ location history.
After you implement your geofencing solution, your geofence collection resource emits the following events:
• ENTER — A tracked device enters a geofence within a geofence collection.
• EXIT — A tracked device exits a geofence within a geofence collection.
You can use Amazon EventBridge to react to events by routing them elsewhere.
As an alternative to sending updates via the Amazon Location Service APIs from each device, you can use MQTT to send device udpates.
The following topics describe these steps and alternatives in detail.
Topics
• Add geofences (p. 125)
• Start tracking (p. 128)
• Link a tracker to a geofence collection (p. 133)
• Evaluate device positions against geofences (p. 134)
• Reacting to Amazon Location Service events with Amazon EventBridge (p. 136)
• Tracking using MQTT with Amazon Location Service (p. 138)
• Managing your geofence collection resources (p. 142)
• Managing your tracker resources (p. 147)
Add geofences
Geofences contain points and vertices that form a closed boundary, which defines an area of interest.
Geofence collections store and manage one or multiple geofences.
Amazon Location geofence collections stores geofences defined by using a standard geospatial data format called GeoJSON (RFC 7946). You can use tools, such as geojson.io, at no charge to draw your geofences graphically and save the output GeoJSON file.
Note
Amazon Location doesn't support polygons with holes, multipolygons, clockwise polygons, and geofences that cross the antimeridian.
Create a geofence collection
Create a geofence collection to store and manage geofences by using the Amazon Location console, the AWS CLI, or the Amazon Location APIs.
Console
To create a geofence collection using the Amazon Location console
Step 1: Add geofences
1. Open the Amazon Location Service console at https://console.aws.amazon.com/location/.
2. In the left navigation pane, choose Geofence collections.
3. Choose Create geofence collection.
4. Fill out the following boxes:
• Name – Enter a unique name. For example, ExampleGeofenceCollection. Maximum 100 characters. Valid entries include alphanumeric characters, hyphens, periods, and underscores.
• Description – Enter an optional description to differentiate your resources.
5. Under EventBridge rule with CloudWatch as a target, you can create an optional EventBridge rule to get started reacting to geofence events. (p. 136) This enables Amazon Location to publish events to Amazon CloudWatch Logs.
6. (Optional) Under Tags, enter a tag Key and Value. This adds a tag your new geofence collection.
For more information, see Tagging your Amazon Location Service resources (p. 150).
7. (Optional) Under Customer managed key encryption, you can choose to Add a customer managed key. This adds a symmetric customer managed key that you create, own, and manage over the default AWS owned encryption. For more information, see Encrypting data at rest (p. 171).
8. Choose Create geofence collection.
API
To create a geofence collection using the Amazon Location APIs
Use the CreateGeofenceCollection operation from the Amazon Location Geofences APIs.
The following example uses an API request to create a geofence collection called
ExampleGeofenceCollection. The geofence collection is associated with a customer managed KMS key to encrypt customer data (p. 171).
POST /geofencing/v0/collections Content-type: application/json
{ "CollectionName": "ExampleGeofenceCollection",
"Description": "Geofence collection 1 for shopping center", "KmsKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Tags": {
"Tag1" : "Value1"
} }
AWS CLI
To create a geofence collection using AWS CLI commands Use the create-geofence-collection command.
The following example uses an AWS CLI to create a geofence collection called
ExampleGeofenceCollection. The geofence collection is associated with a customer managed KMS key to encrypt customer data (p. 171).
aws location \
create-geofence-collection \
--collection-name "ExampleGeofenceCollection" \ --description "Shopping center geofence collection" \ --kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab" \
Step 1: Add geofences
--tags Tag1=Value1
NoteBilling depends on your usage. You may incur fees for the use of other AWS services. For more information, see Amazon Location Service pricing.
Draw geofences using a GeoJSON tool
Now that you've created your geofence collection, you can define your geofences by using a GeoJSON editing tool, such as geojson.io.
To create a GeoJSON file
1. Open a GeoJSON editing tool. For example, geojson.io.
2. Choose the Draw a polygon icon and draw your area of interest.
3. Choose Save, then choose GeoJSON from the dropdown menu.
Put geofences in a geofence collection
You can use the resulting GeoJSON file to upload your geofences using the Amazon Location Service console, the AWS CLI, or the Amazon Location APIs:
Console
To add a geofence to a geofence collection using the Amazon Location Service console 1. Open the Amazon Location Service console at https://console.aws.amazon.com/location/.
2. In the left navigation pane, choose Geofence collections.
3. From the Geofence collections list, select the name link for the target geofence collection.
4. Under Geofences, choose Create geofences.
5. In the Add geofences window, drag, and drop your GeoJSON into the window.
6. Choose Add geofences.
API
To add geofences using the Amazon Location APIs
Use the PutGeofence operation from the Amazon Location Geofences APIs.
The following example uses an API request to add a geofence given the ID GEOFENCE-EXAMPLE1 to a geofence collection called ExampleGeofenceCollection:
PUT /geofencing/v0/collections/ExampleGeofenceCollection/geofence/GEOFENCE-EXAMPLE1 Content-type: application/json
{ "Geometry": { "Polygon": [ [
[-5.716667, -15.933333], [-14.416667, -7.933333], [-12.316667, -37.066667], [-5.716667, -15.933333]
] ]