2021/12/06 - Amazon Location Service - 1 new 6 updated api methods
Changes This release adds support for Accuracy position filtering, position metadata and autocomplete for addresses and points of interest based on partial or misspelled free-form text.
Generates suggestions for addresses and points of interest based on partial or misspelled free-form text. This operation is also known as autocomplete, autosuggest, or fuzzy matching.
Optional parameters let you narrow your search results by bounding box or country, or bias your search toward a specific position on the globe.
Note
You can search for suggested place names near a specified position by using BiasPosition , or filter results within a bounding box by using FilterBBox . These parameters are mutually exclusive; using both BiasPosition and FilterBBox in the same command returns an error.
See also: AWS API Documentation
Request Syntax
client.search_place_index_for_suggestions(
BiasPosition=[
123.0,
],
FilterBBox=[
123.0,
],
FilterCountries=[
'string',
],
IndexName='string',
Language='string',
MaxResults=123,
Text='string'
)
list
An optional parameter that indicates a preference for place suggestions that are closer to a specified position.
If provided, this parameter must contain a pair of numbers. The first number represents the X coordinate, or longitude; the second number represents the Y coordinate, or latitude.
For example, [-123.1174, 49.2847] represents the position with longitude -123.1174 and latitude 49.2847 .
Note
BiasPosition and FilterBBox are mutually exclusive. Specifying both options results in an error.
(float) --
list
An optional parameter that limits the search results by returning only suggestions within a specified bounding box.
If provided, this parameter must contain a total of four consecutive numbers in two pairs. The first pair of numbers represents the X and Y coordinates (longitude and latitude, respectively) of the southwest corner of the bounding box; the second pair of numbers represents the X and Y coordinates (longitude and latitude, respectively) of the northeast corner of the bounding box.
For example, [-12.7935, -37.4835, -12.0684, -36.9542] represents a bounding box where the southwest corner has longitude -12.7935 and latitude -37.4835 , and the northeast corner has longitude -12.0684 and latitude -36.9542 .
Note
FilterBBox and BiasPosition are mutually exclusive. Specifying both options results in an error.
(float) --
list
An optional parameter that limits the search results by returning only suggestions within the provided list of countries.
Use the ISO 3166 3-digit country code. For example, Australia uses three upper-case characters: AUS .
(string) --
string
[REQUIRED]
The name of the place index resource you want to use for the search.
string
The preferred language used to return results. The value must be a valid BCP 47 language tag, for example, en for English.
This setting affects the languages used in the results. It does not change which results are returned. If the language is not specified, or not supported for a particular result, the partner automatically chooses a language for the result.
Used only when the partner selected is Here.
integer
An optional parameter. The maximum number of results returned per request.
The default: 5
string
[REQUIRED]
The free-form partial text to use to generate place suggestions. For example, eiffel tow .
dict
Response Syntax
{
'Results': [
{
'Text': 'string'
},
],
'Summary': {
'BiasPosition': [
123.0,
],
'DataSource': 'string',
'FilterBBox': [
123.0,
],
'FilterCountries': [
'string',
],
'Language': 'string',
'MaxResults': 123,
'Text': 'string'
}
}
Response Structure
(dict) --
Results (list) --
A list of place suggestions that best match the search text.
(dict) --
Contains a place suggestion resulting from a place suggestion query that is run on a place index resource.
Text (string) --
The text of the place suggestion, typically formatted as an address string.
Summary (dict) --
Contains a summary of the request. Echoes the input values for BiasPosition , FilterBBox , FilterCountries , Language , MaxResults , and Text . Also includes the DataSource of the place index.
BiasPosition (list) --
Contains the coordinates for the optional bias position specified in the request.
This parameter contains a pair of numbers. The first number represents the X coordinate, or longitude; the second number represents the Y coordinate, or latitude.
For example, [-123.1174, 49.2847] represents the position with longitude -123.1174 and latitude 49.2847 .
(float) --
DataSource (string) --
The geospatial data provider attached to the place index resource specified in the request. Values can be one of the following:
Esri
Here
For more information about data providers, see Amazon Location Service data providers.
FilterBBox (list) --
Contains the coordinates for the optional bounding box specified in the request.
(float) --
FilterCountries (list) --
Contains the optional country filter specified in the request.
(string) --
Language (string) --
The preferred language used to return results. Matches the language in the request. The value is a valid BCP 47 language tag, for example, en for English.
MaxResults (integer) --
Contains the optional result count limit specified in the request.
Text (string) --
The free-form partial text input specified in the request.
{'DevicePositionUpdates': {'Accuracy': {'Horizontal': 'double'},
'PositionProperties': {'string': 'string'}}}
Evaluates device positions against the geofence geometries from a given geofence collection.
This operation always returns an empty response because geofences are asynchronously evaluated. The evaluation determines if the device has entered or exited a geofenced area, and then publishes one of the following events to Amazon EventBridge:
ENTER if Amazon Location determines that the tracked device has entered a geofenced area.
EXIT if Amazon Location determines that the tracked device has exited a geofenced area.
Note
The last geofence that a device was observed within is tracked for 30 days after the most recent device position update.
Note
Geofence evaluation uses the given device position. It does not account for the optional Accuracy of a DevicePositionUpdate .
See also: AWS API Documentation
Request Syntax
client.batch_evaluate_geofences(
CollectionName='string',
DevicePositionUpdates=[
{
'Accuracy': {
'Horizontal': 123.0
},
'DeviceId': 'string',
'Position': [
123.0,
],
'PositionProperties': {
'string': 'string'
},
'SampleTime': datetime(2015, 1, 1)
},
]
)
string
[REQUIRED]
The geofence collection used in evaluating the position of devices against its geofences.
list
[REQUIRED]
Contains device details for each device to be evaluated against the given geofence collection.
(dict) --
Contains the position update details for a device.
Accuracy (dict) --
The accuracy of the device position.
Horizontal (float) -- [REQUIRED]
Estimated maximum distance, in meters, between the measured position and the true position of a device, along the Earth's surface.
DeviceId (string) -- [REQUIRED]
The device associated to the position update.
Position (list) -- [REQUIRED]
The latest device position defined in WGS 84 format: [X or longitude, Y or latitude] .
(float) --
PositionProperties (dict) --
Associates one of more properties with the position update. A property is a key-value pair stored with the position update and added to any geofence event the update may trigger.
Format: "key" : "value"
(string) --
(string) --
SampleTime (datetime) -- [REQUIRED]
The timestamp at which the device's position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
dict
Response Syntax
{
'Errors': [
{
'DeviceId': 'string',
'Error': {
'Code': 'AccessDeniedError'|'ConflictError'|'InternalServerError'|'ResourceNotFoundError'|'ThrottlingError'|'ValidationError',
'Message': 'string'
},
'SampleTime': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
Errors (list) --
Contains error details for each device that failed to evaluate its position against the given geofence collection.
(dict) --
Contains error details for each device that failed to evaluate its position against the geofences in a given geofence collection.
DeviceId (string) --
The device associated with the position evaluation error.
Error (dict) --
Contains details associated to the batch error.
Code (string) --
The error code associated with the batch request error.
Message (string) --
A message with the reason for the batch request error.
SampleTime (datetime) --
Specifies a timestamp for when the error occurred in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
{'DevicePositions': {'Accuracy': {'Horizontal': 'double'},
'PositionProperties': {'string': 'string'}}}
Lists the latest device positions for requested devices.
See also: AWS API Documentation
Request Syntax
client.batch_get_device_position(
DeviceIds=[
'string',
],
TrackerName='string'
)
list
[REQUIRED]
Devices whose position you want to retrieve.
For example, for two devices: device-ids=DeviceId1&device-ids=DeviceId2
(string) --
string
[REQUIRED]
The tracker resource retrieving the device position.
dict
Response Syntax
{
'DevicePositions': [
{
'Accuracy': {
'Horizontal': 123.0
},
'DeviceId': 'string',
'Position': [
123.0,
],
'PositionProperties': {
'string': 'string'
},
'ReceivedTime': datetime(2015, 1, 1),
'SampleTime': datetime(2015, 1, 1)
},
],
'Errors': [
{
'DeviceId': 'string',
'Error': {
'Code': 'AccessDeniedError'|'ConflictError'|'InternalServerError'|'ResourceNotFoundError'|'ThrottlingError'|'ValidationError',
'Message': 'string'
}
},
]
}
Response Structure
(dict) --
DevicePositions (list) --
Contains device position details such as the device ID, position, and timestamps for when the position was received and sampled.
(dict) --
Contains the device position 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 device whose position you retrieved.
Position (list) --
The last known device position.
(float) --
PositionProperties (dict) --
The properties associated with the position.
(string) --
(string) --
ReceivedTime (datetime) --
The timestamp for when the tracker resource received the device position in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
SampleTime (datetime) --
The timestamp at which the device's position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
Errors (list) --
Contains error details for each device that failed to send its position to the tracker resource.
(dict) --
Contains error details for each device that didn't return a position.
DeviceId (string) --
The ID of the device that didn't return a position.
Error (dict) --
Contains details related to the error code.
Code (string) --
The error code associated with the batch request error.
Message (string) --
A message with the reason for the batch request error.
{'Updates': {'Accuracy': {'Horizontal': 'double'},
'PositionProperties': {'string': 'string'}}}
Uploads position update data for one or more devices to a tracker resource. Amazon Location uses the data when it reports the last known device position and position history. Amazon Location retains location data for 30 days.
Note
Position updates are handled based on the PositionFiltering property of the tracker. When PositionFiltering is set to TimeBased , updates are evaluated against linked geofence collections, and location data is stored at a maximum of one position per 30 second interval. If your update frequency is more often than every 30 seconds, only one update per 30 seconds is stored for each unique device ID.
When PositionFiltering is set to DistanceBased filtering, location data is stored and evaluated against linked geofence collections only if the device has moved more than 30 m (98.4 ft).
When PositionFiltering is set to AccuracyBased filtering, location data is stored and evaluated against linked geofence collections only if the device has moved more than the measured accuracy. For example, if two consecutive updates from a device have a horizontal accuracy of 5 m and 10 m, the second update is neither stored or evaluated if the device has moved less than 15 m. If PositionFiltering is set to AccuracyBased filtering, Amazon Location uses the default value { "Horizontal": 0} when accuracy is not provided on a DevicePositionUpdate .
See also: AWS API Documentation
Request Syntax
client.batch_update_device_position(
TrackerName='string',
Updates=[
{
'Accuracy': {
'Horizontal': 123.0
},
'DeviceId': 'string',
'Position': [
123.0,
],
'PositionProperties': {
'string': 'string'
},
'SampleTime': datetime(2015, 1, 1)
},
]
)
string
[REQUIRED]
The name of the tracker resource to update.
list
[REQUIRED]
Contains the position update details for each device.
(dict) --
Contains the position update details for a device.
Accuracy (dict) --
The accuracy of the device position.
Horizontal (float) -- [REQUIRED]
Estimated maximum distance, in meters, between the measured position and the true position of a device, along the Earth's surface.
DeviceId (string) -- [REQUIRED]
The device associated to the position update.
Position (list) -- [REQUIRED]
The latest device position defined in WGS 84 format: [X or longitude, Y or latitude] .
(float) --
PositionProperties (dict) --
Associates one of more properties with the position update. A property is a key-value pair stored with the position update and added to any geofence event the update may trigger.
Format: "key" : "value"
(string) --
(string) --
SampleTime (datetime) -- [REQUIRED]
The timestamp at which the device's position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
dict
Response Syntax
{
'Errors': [
{
'DeviceId': 'string',
'Error': {
'Code': 'AccessDeniedError'|'ConflictError'|'InternalServerError'|'ResourceNotFoundError'|'ThrottlingError'|'ValidationError',
'Message': 'string'
},
'SampleTime': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
Errors (list) --
Contains error details for each device that failed to update its position.
(dict) --
Contains error details for each device that failed to update its position.
DeviceId (string) --
The device associated with the failed location update.
Error (dict) --
Contains details related to the error code such as the error code and error message.
Code (string) --
The error code associated with the batch request error.
Message (string) --
A message with the reason for the batch request error.
SampleTime (datetime) --
The timestamp at which the device position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
{'Accuracy': {'Horizontal': 'double'},
'PositionProperties': {'string': 'string'}}
Retrieves a device's most recent position according to its sample time.
Note
Device positions are deleted after 30 days.
See also: AWS API Documentation
Request Syntax
client.get_device_position(
DeviceId='string',
TrackerName='string'
)
string
[REQUIRED]
The device whose position you want to retrieve.
string
[REQUIRED]
The tracker resource receiving the position update.
dict
Response Syntax
{
'Accuracy': {
'Horizontal': 123.0
},
'DeviceId': 'string',
'Position': [
123.0,
],
'PositionProperties': {
'string': 'string'
},
'ReceivedTime': datetime(2015, 1, 1),
'SampleTime': datetime(2015, 1, 1)
}
Response Structure
(dict) --
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 device whose position you retrieved.
Position (list) --
The last known device position.
(float) --
PositionProperties (dict) --
The properties associated with the position.
(string) --
(string) --
ReceivedTime (datetime) --
The timestamp for when the tracker resource received the device position in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
SampleTime (datetime) --
The timestamp at which the device's position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
{'DevicePositions': {'Accuracy': {'Horizontal': 'double'},
'PositionProperties': {'string': 'string'}}}
Retrieves the device position history from a tracker resource within a specified range of time.
Note
Device positions are deleted after 30 days.
See also: AWS API Documentation
Request Syntax
client.get_device_position_history(
DeviceId='string',
EndTimeExclusive=datetime(2015, 1, 1),
NextToken='string',
StartTimeInclusive=datetime(2015, 1, 1),
TrackerName='string'
)
string
[REQUIRED]
The device whose position history you want to retrieve.
datetime
Specify the end time for the position history in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ . By default, the value will be the time that the request is made.
Requirement:
The time specified for EndTimeExclusive must be after the time for StartTimeInclusive .
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
datetime
Specify the start time for the position history in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ . By default, the value will be 24 hours prior to the time that the request is made.
Requirement:
The time specified for StartTimeInclusive must be before EndTimeExclusive .
string
[REQUIRED]
The tracker resource receiving the request for the device position history.
dict
Response Syntax
{
'DevicePositions': [
{
'Accuracy': {
'Horizontal': 123.0
},
'DeviceId': 'string',
'Position': [
123.0,
],
'PositionProperties': {
'string': 'string'
},
'ReceivedTime': datetime(2015, 1, 1),
'SampleTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
DevicePositions (list) --
Contains the position history details for the requested device.
(dict) --
Contains the device position 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 device whose position you retrieved.
Position (list) --
The last known device position.
(float) --
PositionProperties (dict) --
The properties associated with the position.
(string) --
(string) --
ReceivedTime (datetime) --
The timestamp for when the tracker resource received the device position in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
SampleTime (datetime) --
The timestamp at which the device's 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.
{'Entries': {'Accuracy': {'Horizontal': 'double'},
'PositionProperties': {'string': 'string'}}}
A batch request to retrieve all device positions.
See also: AWS API Documentation
Request Syntax
client.list_device_positions(
MaxResults=123,
NextToken='string',
TrackerName='string'
)
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. These details includes the device ID, the time when the position was sampled on the device, the time that the service received the update, and the most recent coordinates.
(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.