2023/10/03 - Amazon Location Service - 5 updated api methods
Changes Amazon Location Service adds support for bounding polygon queries. Additionally, the GeofenceCount field has been added to the DescribeGeofenceCollection API response.
{'KmsKeyEnableGeospatialQueries': 'boolean'}
Creates a tracker resource in your Amazon Web Services account, which lets you retrieve current and historical location of devices.
See also: AWS API Documentation
Request Syntax
client.create_tracker(
Description='string',
EventBridgeEnabled=True|False,
KmsKeyEnableGeospatialQueries=True|False,
KmsKeyId='string',
PositionFiltering='TimeBased'|'DistanceBased'|'AccuracyBased',
PricingPlan='RequestBasedUsage'|'MobileAssetTracking'|'MobileAssetManagement',
PricingPlanDataSource='string',
Tags={
'string': 'string'
},
TrackerName='string'
)
string
An optional description for the tracker resource.
boolean
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.
boolean
Enables GeospatialQueries for a tracker that uses a Amazon Web Services 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.
string
A key identifier for an Amazon Web Services KMS customer managed key. Enter a key ID, key ARN, alias name, or alias ARN.
string
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 .
string
No longer used. If included, the only allowed value is RequestBasedUsage .
string
This parameter is no longer used.
dict
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.
(string) --
(string) --
string
[REQUIRED]
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 .
dict
Response Syntax
{
'CreateTime': datetime(2015, 1, 1),
'TrackerArn': 'string',
'TrackerName': 'string'
}
Response Structure
(dict) --
CreateTime (datetime) --
The timestamp for when the tracker resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
TrackerArn (string) --
The Amazon Resource Name (ARN) for the tracker resource. Used when you need to specify a resource across all Amazon Web Services.
Format example: arn:aws:geo:region:account-id:tracker/ExampleTracker
TrackerName (string) --
The name of the tracker resource.
{'GeofenceCount': 'integer'}
Retrieves the geofence collection details.
See also: AWS API Documentation
Request Syntax
client.describe_geofence_collection(
CollectionName='string'
)
string
[REQUIRED]
The name of the geofence collection.
dict
Response Syntax
{
'CollectionArn': 'string',
'CollectionName': 'string',
'CreateTime': datetime(2015, 1, 1),
'Description': 'string',
'GeofenceCount': 123,
'KmsKeyId': 'string',
'PricingPlan': 'RequestBasedUsage'|'MobileAssetTracking'|'MobileAssetManagement',
'PricingPlanDataSource': 'string',
'Tags': {
'string': 'string'
},
'UpdateTime': datetime(2015, 1, 1)
}
Response Structure
(dict) --
CollectionArn (string) --
The Amazon Resource Name (ARN) for the geofence collection resource. Used when you need to specify a resource across all Amazon Web Services.
Format example: arn:aws:geo:region:account-id:geofence-collection/ExampleGeofenceCollection
CollectionName (string) --
The name of the geofence collection.
CreateTime (datetime) --
The timestamp for when the geofence resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
Description (string) --
The optional description for the geofence collection.
GeofenceCount (integer) --
The number of geofences in the geofence collection.
KmsKeyId (string) --
A key identifier for an Amazon Web Services KMS customer managed key assigned to the Amazon Location resource
PricingPlan (string) --
No longer used. Always returns RequestBasedUsage .
PricingPlanDataSource (string) --
No longer used. Always returns an empty string.
Tags (dict) --
Displays the key, value pairs of tags associated with this resource.
(string) --
(string) --
UpdateTime (datetime) --
The timestamp for when the geofence collection was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
{'KmsKeyEnableGeospatialQueries': 'boolean'}
Retrieves the tracker resource details.
See also: AWS API Documentation
Request Syntax
client.describe_tracker(
TrackerName='string'
)
string
[REQUIRED]
The name of the tracker resource.
dict
Response Syntax
{
'CreateTime': datetime(2015, 1, 1),
'Description': 'string',
'EventBridgeEnabled': True|False,
'KmsKeyEnableGeospatialQueries': True|False,
'KmsKeyId': 'string',
'PositionFiltering': 'TimeBased'|'DistanceBased'|'AccuracyBased',
'PricingPlan': 'RequestBasedUsage'|'MobileAssetTracking'|'MobileAssetManagement',
'PricingPlanDataSource': 'string',
'Tags': {
'string': 'string'
},
'TrackerArn': 'string',
'TrackerName': 'string',
'UpdateTime': datetime(2015, 1, 1)
}
Response Structure
(dict) --
CreateTime (datetime) --
The timestamp for when the tracker resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
Description (string) --
The optional description for the tracker resource.
EventBridgeEnabled (boolean) --
Whether UPDATE events from this tracker in EventBridge are enabled. If set to true these events will be sent to EventBridge.
KmsKeyEnableGeospatialQueries (boolean) --
Enables GeospatialQueries for a tracker that uses a Amazon Web Services 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.
KmsKeyId (string) --
A key identifier for an Amazon Web Services KMS customer managed key assigned to the Amazon Location resource.
PositionFiltering (string) --
The position filtering method of the tracker resource.
PricingPlan (string) --
Always returns RequestBasedUsage .
PricingPlanDataSource (string) --
No longer used. Always returns an empty string.
Tags (dict) --
The tags associated with the tracker resource.
(string) --
(string) --
TrackerArn (string) --
The Amazon Resource Name (ARN) for the tracker resource. Used when you need to specify a resource across all Amazon Web Services.
Format example: arn:aws:geo:region:account-id:tracker/ExampleTracker
TrackerName (string) --
The name of the tracker resource.
UpdateTime (datetime) --
The timestamp for when the tracker resource was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
{'FilterGeometry': {'Polygon': [[['double']]]}}
A batch request to retrieve all device positions.
See also: AWS API Documentation
Request Syntax
client.list_device_positions(
FilterGeometry={
'Polygon': [
[
[
123.0,
],
],
]
},
MaxResults=123,
NextToken='string',
TrackerName='string'
)
dict
The geomerty used to filter device positions.
Polygon (list) --
The set of arrays which define the polygon. A polygon can have between 4 and 1000 vertices.
(list) --
(list) --
(float) --
integer
An optional limit for the number of entries returned in a single call.
Default value: 100
string
The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.
Default value: null
string
[REQUIRED]
The tracker resource containing the requested devices.
dict
Response Syntax
{
'Entries': [
{
'Accuracy': {
'Horizontal': 123.0
},
'DeviceId': 'string',
'Position': [
123.0,
],
'PositionProperties': {
'string': 'string'
},
'SampleTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Entries (list) --
Contains details about each device's last known position.
(dict) --
Contains the tracker resource details.
Accuracy (dict) --
The accuracy of the device position.
Horizontal (float) --
Estimated maximum distance, in meters, between the measured position and the true position of a device, along the Earth's surface.
DeviceId (string) --
The ID of the device for this position.
Position (list) --
The last known device position. Empty if no positions currently stored.
(float) --
PositionProperties (dict) --
The properties associated with the position.
(string) --
(string) --
SampleTime (datetime) --
The timestamp at which the device position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
NextToken (string) --
A pagination token indicating there are additional pages available. You can use the token in a following request to fetch the next set of results.
{'KmsKeyEnableGeospatialQueries': 'boolean'}
Updates the specified properties of a given tracker resource.
See also: AWS API Documentation
Request Syntax
client.update_tracker(
Description='string',
EventBridgeEnabled=True|False,
KmsKeyEnableGeospatialQueries=True|False,
PositionFiltering='TimeBased'|'DistanceBased'|'AccuracyBased',
PricingPlan='RequestBasedUsage'|'MobileAssetTracking'|'MobileAssetManagement',
PricingPlanDataSource='string',
TrackerName='string'
)
string
Updates the description for the tracker resource.
boolean
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.
boolean
Enables GeospatialQueries for a tracker that uses a Amazon Web Services KMS customer managed key.
This parameter is only used if you are using a KMS customer managed key.
string
Updates 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 distance 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 helps educe the effects of GPS noise when displaying device trajectories on a map, and can help control costs by reducing the number of geofence evaluations.
string
No longer used. If included, the only allowed value is RequestBasedUsage .
string
This parameter is no longer used.
string
[REQUIRED]
The name of the tracker resource to update.
dict
Response Syntax
{
'TrackerArn': 'string',
'TrackerName': 'string',
'UpdateTime': datetime(2015, 1, 1)
}
Response Structure
(dict) --
TrackerArn (string) --
The Amazon Resource Name (ARN) of the updated tracker resource. Used to specify a resource across AWS.
Format example: arn:aws:geo:region:account-id:tracker/ExampleTracker
TrackerName (string) --
The name of the updated tracker resource.
UpdateTime (datetime) --
The timestamp for when the tracker resource was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .