CreateTracker - Amazon Location Service

CreateTracker

Creates a tracker resource in your AWS account, which lets you retrieve current and historical location of devices.

Request Syntax

POST /tracking/v0/trackers HTTP/1.1 Content-type: application/json { "Description": "string", "EventBridgeEnabled": boolean, "KmsKeyEnableGeospatialQueries": boolean, "KmsKeyId": "string", "PositionFiltering": "string", "PricingPlan": "string", "PricingPlanDataSource": "string", "Tags": { "string" : "string" }, "TrackerName": "string" }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

Description

An optional description for the tracker resource.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1000.

Required: No

EventBridgeEnabled

Whether to enable position UPDATE events from this tracker to be sent to EventBridge.

Note

You do not need enable this feature to get ENTER and EXIT events for geofences with this tracker. Those events are always sent to EventBridge.

Type: Boolean

Required: No

KmsKeyEnableGeospatialQueries

Enables GeospatialQueries for a tracker that uses a AWS KMS customer managed key.

This parameter is only used if you are using a KMS customer managed key.

Note

If you wish to encrypt your data using your own KMS customer managed key, then the Bounding Polygon Queries feature will be disabled by default. This is because by using this feature, a representation of your device positions will not be encrypted using the your KMS managed key. The exact device position, however; is still encrypted using your managed key.

You can choose to opt-in to the Bounding Polygon Quseries feature. This is done by setting the KmsKeyEnableGeospatialQueries parameter to true when creating or updating a Tracker.

Type: Boolean

Required: No

KmsKeyId

A key identifier for an AWS KMS customer managed key. Enter a key ID, key ARN, alias name, or alias ARN.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

PositionFiltering

Specifies the position filtering for the tracker resource.

Valid values:

  • TimeBased - Location updates are 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.

  • DistanceBased - If the device has moved less than 30 m (98.4 ft), location updates are ignored. Location updates within this area are neither evaluated against linked geofence collections, nor stored. This helps control costs by reducing the number of geofence evaluations and historical device positions to paginate through. Distance-based filtering can also reduce the effects of GPS noise when displaying device trajectories on a map.

  • AccuracyBased - If the device has moved less than the measured accuracy, location updates are ignored. For example, if two consecutive updates from a device have a horizontal accuracy of 5 m and 10 m, the second update is ignored if the device has moved less than 15 m. Ignored location updates are neither evaluated against linked geofence collections, nor stored. This can reduce the effects of GPS noise when displaying device trajectories on a map, and can help control your costs by reducing the number of geofence evaluations.

This field is optional. If not specified, the default value is TimeBased.

Type: String

Valid Values: TimeBased | DistanceBased | AccuracyBased

Required: No

PricingPlan

This parameter has been deprecated.

No longer used. If included, the only allowed value is RequestBasedUsage.

Type: String

Valid Values: RequestBasedUsage | MobileAssetTracking | MobileAssetManagement

Required: No

PricingPlanDataSource

This parameter has been deprecated.

This parameter is no longer used.

Type: String

Required: No

Tags

Applies one or more tags to the tracker resource. A tag is a key-value pair helps manage, identify, search, and filter your resources by labelling them.

Format: "key" : "value"

Restrictions:

  • Maximum 50 tags per resource

  • Each resource tag must be unique with a maximum of one value.

  • Maximum key length: 128 Unicode characters in UTF-8

  • Maximum value length: 256 Unicode characters in UTF-8

  • Can use alphanumeric characters (A–Z, a–z, 0–9), and the following characters: + - = . _ : / @.

  • Cannot use "aws:" as a prefix for a key.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: ([\p{L}\p{Z}\p{N}_.,:/=+\-@]*)

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: ([\p{L}\p{Z}\p{N}_.,:/=+\-@]*)

Required: No

TrackerName

The name for the tracker resource.

Requirements:

  • Contain only alphanumeric characters (A-Z, a-z, 0-9) , hyphens (-), periods (.), and underscores (_).

  • Must be a unique tracker resource name.

  • No spaces allowed. For example, ExampleTracker.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: [-._\w]+

Required: Yes

Response Syntax

HTTP/1.1 200 Content-type: application/json { "CreateTime": "string", "TrackerArn": "string", "TrackerName": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

CreateTime

The timestamp for when the tracker resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.

Type: Timestamp

TrackerArn

The Amazon Resource Name (ARN) for the tracker resource. Used when you need to specify a resource across all AWS.

  • Format example: arn:aws:geo:region:account-id:tracker/ExampleTracker

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1600.

Pattern: arn(:[a-z0-9]+([.-][a-z0-9]+)*){2}(:([a-z0-9]+([.-][a-z0-9]+)*)?){2}:([^/].*)?

TrackerName

The name of the tracker resource.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: [-._\w]+

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The request was denied because of insufficient access or permissions. Check with an administrator to verify your permissions.

HTTP Status Code: 403

ConflictException

The request was unsuccessful because of a conflict.

HTTP Status Code: 409

InternalServerException

The request has failed to process because of an unknown server error, exception, or failure.

HTTP Status Code: 500

ServiceQuotaExceededException

The operation was denied because the request would exceed the maximum quota set for Amazon Location Service.

HTTP Status Code: 402

ThrottlingException

The request was denied because of request throttling.

HTTP Status Code: 429

ValidationException

The input failed to meet the constraints specified by the AWS service.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: