} }
Alternatively, you can add more than one geofence using the BatchPutGeofence operation.
POST /geofencing/v0/collections/ExampleGeofenceCollection/put-geofences Content-type: application/json
{ "Entries": [ {
"GeofenceId": "GEOFENCE-EXAMPLE1", "Geometry": {
"Polygon": [ [
[-5.716667, -15.933333], [-14.416667, -7.933333], [-12.316667, -37.066667], [-5.716667, -15.933333]
] ] } } ]}
AWS CLI
To add a geofence to a geofence collection using AWS CLI commands Use the put-geofence command.
The following example uses an AWS CLI to add a geofence to a geofence collection called ExampleGeofenceCollection.
$ aws location \ put-geofence \
--collection-name ExampleGeofenceCollection \ --geofence-id ExampleGeofenceTriangle \
--geometry 'Polygon=[[[-5.716667, -15.933333],[-14.416667, -7.933333], [-12.316667, -37.066667],[-5.716667, -15.933333]]]'
{
"CreateTime": "2020-11-11T00:16:14.487000+00:00", "GeofenceId": "ExampleGeofenceTriangle",
"UpdateTime": "2020-11-11T00:19:59.894000+00:00"
}
Start tracking
This section guides you through building a tracking application that captures device locations.
Create a tracker
Create a tracker resource to store and process position updates from your devices. You can use the Amazon Location Service console, the AWS CLI, or the Amazon Location APIs.
Each position update stored in your tracker resources can include a measure of position accuracy, and up to 3 fields of metadata about the position or device that you want to store. The metadata is stored as key-value pairs, and can store information such as speed, direction, tire pressure, or engine temperature.
Step 2: Start tracking
Trackers filter position updates as they are received, reducing visual noise in your device paths (called jitter), reducing the number of false geofence entry and exit events, and helping manage costs by reducing the number of position updates stored and geofence evaluations triggered.
Trackers offer three position filtering options to help manage costs and reduce jitter in your location updates.
• Accuracy-based – Use with any device that provides an accuracy measurement. Most mobile devices provide this information. The accuracy of each position measurement is affected by many environmental factors, including GPS satellite reception, landscape, and the proximity of wifi and bluetooth devices. Most devices, including most mobile devices, can provide an estimate of the accuracy of the measurement along with the measurement. With AccuracyBased filtering, Amazon Location ignores location updates if the device moved less than the measured accuracy. For example, if two consecutive updates from a device have an accuracy range of 5 m and 10 m, Amazon Location ignores the second update if the device has moved less than 15 m. Amazon Location neither evaluates ignored updates against geofences, nor stores them.
When accuracy is not provided, it is treated as zero, and the measurement is considered perfectly accurate.
NoteYou can also use accuracy-based filtering to remove all filtering. If you select accuracy-based filtering, but override all accuracy data to zero, or omit the accuracy entirely, then Amazon Location will not filter out any updates.
• Distance-based – Use when your devices do not provide an accuracy measurement, but you still want to take advantage of filtering to reduce jitter and manage costs. DistanceBased filtering ignores location updates in which devices have moved less than 30 m (98.4 ft). When you use DistanceBased position filtering, Amazon Location neither evaluates these ignored updates against geofences nor stores the updates.
The accuracy of most mobile devices, including the average accuracy of iOS and Android devices, is within 15 m. In most applications, DistanceBased filtering can reduce the effect of location inaccuracies when displaying device trajectory on a map, and the bouncing effect of multiple consecutive entry and exit events when devices are near the border of a geofence. It can also help reduce the cost of your application, by making fewer calls to evaluate against linked geofences or retrieve device positions.
• Time-based – (default) Use when your devices send position updates very frequently (more than once every 30 seconds), and you want to achieve near real-time geofence evaluations without storing every update. In TimeBased filtering, every location update is evaluated against linked geofence collections, but not every location update is stored. If your update frequency is more often than 30 seconds, only one update per 30 seconds is stored for each unique device ID.
Note
Be mindful of the costs of your tracking application when deciding your filtering method and the frequency of position updates. You are billed for every location update and once for evaluating the position update against each linked geofence collection. For example, when using time-based filtering, if your tracker is linked to two geofence collections, every position update will count as one location update request and two geofence collection evaluations. If you are reporting position updates every 5 seconds for your devices and using time-based filtering, you will be billed for 720 location updates and 1,440 geofence evaluations per hour for each device.
Your bill is not affected by the number of geofences in each collection. Since each geofence collection may contain up to 50,000 geofences, you may want to combine your geofences into fewer collections, where possible, to reduce your cost of geofence evaluations.
Console
To create a tracker using the Amazon Location console
Step 2: Start tracking
1. Open the Amazon Location Service console at https://console.aws.amazon.com/location/.
2. In the left navigation pane, choose Trackers.
3. Choose Create tracker.
4. Fill the following fields:
• Name – Enter a unique name. For example, ExampleTracker. Maximum 100 characters.
Valid entries include alphanumeric characters, hyphens, periods, and underscores.
• Description – Enter an optional description.
5. Under Position filtering, choose the option that best fits how you intend to use your tracker resource. If you do not set Position filtering, the default setting is TimeBased. For more information, see Trackers (p. 21) in this guide, and PositionFiltering in the Amazon Location Service Trackers API reference.
6. (Optional) Under Tags, enter a tag Key and Value. This adds a tag your new geofence collection.
For more information, see Tagging your 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 tracker.
API
To create a tracker by using the Amazon Location APIs
Use the CreateTracker operation from the Amazon Location Trackers APIs.
The following example uses an API request to create a tracker called ExampleTracker. The tracker resource is associated with a customer managed KMS key to encrypt customer data (p. 171).
POST /tracking/v0/trackers Content-type: application/json {
"TrackerName": "ExampleTracker", "Description": "string",
"KmsKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "PositionFiltering": "AccuracyBased",
"Tags": {
"string" : "string"
}}
AWS CLI
To create a tracker using AWS CLI commands Use the create-tracker command.
The following example uses the AWS CLI to create a tracker called ExampleTracker. The tracker resource is associated with a customer managed KMS key to encrypt customer data (p. 171).
aws location \ create-tracker \
--tracker-name "ExampleTracker" \
Step 2: Start tracking
--position-filtering "AccuracyBased" \
--kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab"
NoteBilling depends on your usage. You may incur fees for the use of other AWS services. For more information, see Amazon Location Service pricing.
Authenticating your requests
Once you create a tracker resource and you're ready to begin evaluating device positions against geofences, choose how you would authenticate your requests:
• To explore ways you can access the services, see Accessing Amazon Location Service (p. 153).
• If you have a website with anonymous users, or you want to use your own authentication process, or combine multiple authentication methods, see Allowing unauthenticated guest access to your application using Amazon Cognito (p. 154).
Example
The following example shows the passing of the unauthenticated identity pool as credentials when using the AWS JavaScript SDK.
const AWS = require("aws-sdk");
// Exchange the unauthenticated identity pool you created for credentials const credentials = new AWS.CognitoIdentityCredentials({
IdentityPoolId: "us-east-1:54f2ba88-9390-498d-aaa5-0d97fb7ca3bd"
});
const client = new AWS.Location({
credentials,
region: "us-east-1" // The region containing both the identity pool and tracker resource
});
// Send device position updates const rsp = await location .batchUpdateDevicePosition({
TrackerName: "ExampleTracker", Updates: [
{
DeviceId: "ExampleDevice-1", Position: [-123.4567, 45.6789],
SampleTime: "2020-10-02T19:09:07.327Z"
}, {
DeviceId: "ExampleDevice-2", Position: [-123.123, 45.123], SampleTime: "2020-10-02T19:10:32Z"
} ] }) .promise()
Update your tracker with a device position
To track your devices, you can post device position updates to your tracker. You can later retrieve these device positions or the device position history from your tracker resource.
Step 2: Start tracking
Each position update must include the device ID, a time stamp, and a position. You may optionally include other metadata, including accuracy and up to 3 key-value pairs for your own use.
If your tracker is linked to one or more geofence collections, updates will be evaluated against those geofences (following the filtering rules that you specified for the tracker). If a device breaches a geofenced area (by moving from inside the area to outside, or vice versa), you will receive events in EventBridge. These ENTER or EXIT events include the position update details, including the device ID, the timestamp, and any associated metadata.
NoteFor more information about position filtering, see Create a tracker (p. 128).
For more information about geofence events, see Reacting to Amazon Location Service events with Amazon EventBridge (p. 136).
Use any of these methods to send device updates:
• Integrate the tracking SDK in your Android and iOS application.
• Send MQTT updates to an AWS IoT Core resource and link it to your tracker resource.
• Send location updates using the Amazon Location Trackers API, by using the AWS CLI, or the Amazon Location APIs.
API
To send a position update using the Amazon Location APIs
Use the BatchUpdateDevicePosition operation from the Amazon Location Trackers APIs.
The following example uses an API request to post a device position update for ExampleDevice to a tracker ExampleTracker.
POST /tracking/v0/trackers/ExampleTracker/positions Content-type: application/json
{
"Updates": [ {
"DeviceId": "ExampleDevice", "Position": [-123.17805, 49.19284], "SampleTime": "2020-10-02T19:09:07.327Z", "Accuracy": {
"Horizontal": 3.14 },
"PositionProperties": { "field1": "value1", "field2": "value2"
} } ]}
AWS CLI
To send a position update using AWS CLI commands Use the batch-update-device-position command.
The following example uses an AWS CLI to post a device position update for ExampleDevice-1 and ExampleDevice-2 to a tracker ExampleTracker.
aws location batch-update-device-position \ --tracker-name ExampleTracker \