Start tracking - Amazon Location Service

Start tracking

This section guides you through building a tracking application that captures device locations.

Create a tracker

Create a tracker resource to receive location updates from devices capable of transmitting a location update, such as a mobile phone or GPS receiver. This allows you to monitor multiple assets as they move. You can use the Amazon Location Service console, the AWS CLI, or the Amazon Location APIs.

Console

To create a tracker using the Amazon Location console

  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 out the following boxes:

    • 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 Pricing Plan, choose answers that best fit how you intend to use your tracker resource. For more information, see Pricing on the Amazon Location Service product page.

    • For Mobile Asset Tracking or Mobile Asset Management pricing plans, you must associate at least one tracker and send at least one location update per month.

  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.

  7. Choose Create tracker.

API

To create a tracker 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, and a request-based usage pricing plan. The tracker resource is associated with a customer managed KMS key to encrypt customer data.

POST /tracking/v0/trackers Content-type: application/json { "TrackerName": "ExampleTracker", "Description": "string", "KmsKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "PricingPlan": "RequestBasedUsage", "Tags": { "string" : "string" } }
AWS CLI

To create a tracker using AWS CLI commands

Use the create-tracker command.

The following example uses an AWS CLI to create a tracker called ExampleTracker, and a request-based usage pricing plan. The tracker resource is associated with a customer managed KMS key to encrypt customer data.

aws location \ create-tracker \ --tracker-name "ExampleTracker" \ --pricing-plan "RequestBasedUsage" \ --kms-key-id "1234abcd-12ab-34cd-56ef-1234567890ab"
Note

Billing depends on your pricing plan and 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.

  • 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 aplication using Amazon Cognito.

    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.

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" } ] }
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 \ --updates \ "DeviceId=ExampleDevice-1,Position=-123.123,47.123,SampleTime=2020-11-10T12:45:34.123Z" \ "DeviceId=ExampleDevice-2,Position=-123.123,47.123,SampleTime=2020-11-10T12:45:34.123Z"

Get a device's location history from a tracker

Your Amazon Location tracker resource maintains the location history of all your tracked devices for a period of one year. You can retrieve device location history from a tracker. The following examples use the AWS CLI, or the Amazon Location APIs.

API

To get the device location history from a tracker using the Amazon Location APIs

Use the GetDevicePositionHistory operation from the Amazon Location Trackers APIs.

The following example uses an API URI request to get the device location history of ExampleDevice from a tracker called ExampleTracker starting from 19:05:07 (inclusive) and ends at 19:20:07 (exclusive) on 2020–10–02.

POST /tracking/v0/trackers/ExampleTracker/devices/ExampleDevice/list-positions Content-type: application/json { "StartTimeInclusive": "2020-10-02T19:05:07.327Z", "EndTimeExclusive": "2020-10-02T19:20:07.327Z" }
AWS CLI

To get the device location history from a tracker using AWS CLI commands

Use the get-device-position-history command.

The following example uses an AWS CLI to get the device location history of ExampleDevice from a tracker called ExampleTracker starting from 19:05:07 (inclusive) and ends at 19:20:07 (exclusive) on 2020–10–02.

aws location \ get-device-position-history \ --device-id "ExampleDevice" \ --start-time-inclusive "2020-10-02T19:05:07.327Z" \ --end-time-exclusive "2020-10-02T19:20:07.327Z" \ --tracker-name "ExampleTracker"