2024/06/06 - Amazon Location Service - 2 new 4 updated api methods
Changes Added two new APIs, VerifyDevicePosition and ForecastGeofenceEvents. Added support for putting larger geofences up to 100,000 vertices with Geobuf fields.
Evaluates device positions against geofence geometries from a given geofence collection. The event forecasts three states for which a device can be in relative to a geofence:
ENTER : If a device is outside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.
EXIT : If a device is inside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.
IDLE : If a device is inside of a geofence, and the device is not moving.
See also: AWS API Documentation
Request Syntax
client.forecast_geofence_events(
CollectionName='string',
DeviceState={
'Position': [
123.0,
],
'Speed': 123.0
},
TimeHorizonMinutes=123.0,
DistanceUnit='Kilometers'|'Miles',
SpeedUnit='KilometersPerHour'|'MilesPerHour',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The name of the geofence collection.
dict
[REQUIRED]
The device's state, including current position and speed.
Position (list) -- [REQUIRED]
The device's position.
(float) --
Speed (float) --
The device's speed.
float
Specifies the time horizon in minutes for the forecasted events.
string
The distance unit used for the NearestDistance property returned in a forecasted event. The measurement system must match for DistanceUnit and SpeedUnit ; if Kilometers is specified for DistanceUnit , then SpeedUnit must be KilometersPerHour .
Default Value: Kilometers
string
The speed unit for the device captured by the device state. The measurement system must match for DistanceUnit and SpeedUnit ; if Kilometers is specified for DistanceUnit , then SpeedUnit must be KilometersPerHour .
Default Value: KilometersPerHour .
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
integer
An optional limit for the number of resources returned in a single call.
Default value: 20
dict
Response Syntax
{
'ForecastedEvents': [
{
'EventId': 'string',
'GeofenceId': 'string',
'IsDeviceInGeofence': True|False,
'NearestDistance': 123.0,
'EventType': 'ENTER'|'EXIT'|'IDLE',
'ForecastedBreachTime': datetime(2015, 1, 1),
'GeofenceProperties': {
'string': 'string'
}
},
],
'NextToken': 'string',
'DistanceUnit': 'Kilometers'|'Miles',
'SpeedUnit': 'KilometersPerHour'|'MilesPerHour'
}
Response Structure
(dict) --
ForecastedEvents (list) --
The list of forecasted events.
(dict) --
A forecasted event represents a geofence event in relation to the requested device state, that may occur given the provided device state and time horizon.
EventId (string) --
The forecasted event identifier.
GeofenceId (string) --
The geofence identifier pertaining to the forecasted event.
IsDeviceInGeofence (boolean) --
Indicates if the device is located within the geofence.
NearestDistance (float) --
The closest distance from the device's position to the geofence.
EventType (string) --
The event type, forecasting three states for which a device can be in relative to a geofence:
ENTER : If a device is outside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.
EXIT : If a device is inside of a geofence, but would breach the fence if the device is moving at its current speed within time horizon window.
IDLE : If a device is inside of a geofence, and the device is not moving.
ForecastedBreachTime (datetime) --
The forecasted time the device will breach the geofence in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
GeofenceProperties (dict) --
The geofence properties.
(string) --
(string) --
NextToken (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.
DistanceUnit (string) --
The distance unit for the forecasted events.
SpeedUnit (string) --
The speed unit for the forecasted events.
Verifies the integrity of the device's position by determining if it was reported behind a proxy, and by comparing it to an inferred position estimated based on the device's state.
See also: AWS API Documentation
Request Syntax
client.verify_device_position(
TrackerName='string',
DeviceState={
'DeviceId': 'string',
'SampleTime': datetime(2015, 1, 1),
'Position': [
123.0,
],
'Accuracy': {
'Horizontal': 123.0
},
'Ipv4Address': 'string',
'WiFiAccessPoints': [
{
'MacAddress': 'string',
'Rss': 123
},
],
'CellSignals': {
'LteCellDetails': [
{
'CellId': 123,
'Mcc': 123,
'Mnc': 123,
'LocalId': {
'Earfcn': 123,
'Pci': 123
},
'NetworkMeasurements': [
{
'Earfcn': 123,
'CellId': 123,
'Pci': 123,
'Rsrp': 123,
'Rsrq': ...
},
],
'TimingAdvance': 123,
'NrCapable': True|False,
'Rsrp': 123,
'Rsrq': ...,
'Tac': 123
},
]
}
},
DistanceUnit='Kilometers'|'Miles'
)
string
[REQUIRED]
The name of the tracker resource to be associated with verification request.
dict
[REQUIRED]
The device's state, including position, IP address, cell signals and Wi-Fi access points.
DeviceId (string) -- [REQUIRED]
The device identifier.
SampleTime (datetime) -- [REQUIRED]
The timestamp at which the device's position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
Position (list) -- [REQUIRED]
The last known device position.
(float) --
Accuracy (dict) --
Defines the level of certainty of the 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.
Ipv4Address (string) --
The device's Ipv4 address.
WiFiAccessPoints (list) --
The Wi-Fi access points the device is using.
(dict) --
Wi-Fi access point.
MacAddress (string) -- [REQUIRED]
Medium access control address (Mac).
Rss (integer) -- [REQUIRED]
Received signal strength (dBm) of the WLAN measurement data.
CellSignals (dict) --
The cellular network infrastructure that the device is connected to.
LteCellDetails (list) -- [REQUIRED]
Information about the Long-Term Evolution (LTE) network the device is connected to.
(dict) --
Details about the Long-Term Evolution (LTE) network.
CellId (integer) -- [REQUIRED]
The E-UTRAN Cell Identifier (ECI).
Mcc (integer) -- [REQUIRED]
The Mobile Country Code (MCC).
Mnc (integer) -- [REQUIRED]
The Mobile Network Code (MNC)
LocalId (dict) --
The LTE local identification information (local ID).
Earfcn (integer) -- [REQUIRED]
E-UTRA (Evolved Universal Terrestrial Radio Access) absolute radio frequency channel number (EARFCN).
Pci (integer) -- [REQUIRED]
Physical Cell ID (PCI).
NetworkMeasurements (list) --
The network measurements.
(dict) --
LTE network measurements.
Earfcn (integer) -- [REQUIRED]
E-UTRA (Evolved Universal Terrestrial Radio Access) absolute radio frequency channel number (EARFCN).
CellId (integer) -- [REQUIRED]
E-UTRAN Cell Identifier (ECI).
Pci (integer) -- [REQUIRED]
Physical Cell ID (PCI).
Rsrp (integer) --
Signal power of the reference signal received, measured in dBm (decibel-milliwatts).
Rsrq (float) --
Signal quality of the reference Signal received, measured in decibels (dB).
TimingAdvance (integer) --
Timing Advance (TA).
NrCapable (boolean) --
Indicates whether the LTE object is capable of supporting NR (new radio).
Rsrp (integer) --
Signal power of the reference signal received, measured in decibel-milliwatts (dBm).
Rsrq (float) --
Signal quality of the reference Signal received, measured in decibels (dB).
Tac (integer) --
LTE Tracking Area Code (TAC).
string
The distance unit for the verification request.
Default Value: Kilometers
dict
Response Syntax
{
'InferredState': {
'Position': [
123.0,
],
'Accuracy': {
'Horizontal': 123.0
},
'DeviationDistance': 123.0,
'ProxyDetected': True|False
},
'DeviceId': 'string',
'SampleTime': datetime(2015, 1, 1),
'ReceivedTime': datetime(2015, 1, 1),
'DistanceUnit': 'Kilometers'|'Miles'
}
Response Structure
(dict) --
InferredState (dict) --
The inferred state of the device, given the provided position, IP address, cellular signals, and Wi-Fi- access points.
Position (list) --
The device position inferred by the provided position, IP address, cellular signals, and Wi-Fi- access points.
(float) --
Accuracy (dict) --
The level of certainty of the inferred position.
Horizontal (float) --
Estimated maximum distance, in meters, between the measured position and the true position of a device, along the Earth's surface.
DeviationDistance (float) --
The distance between the inferred position and the device's self-reported position.
ProxyDetected (boolean) --
Indicates if a proxy was used.
DeviceId (string) --
The device identifier.
SampleTime (datetime) --
The timestamp at which the device's position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
ReceivedTime (datetime) --
The timestamp for when the tracker resource received the device position in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ .
DistanceUnit (string) --
The distance unit for the verification response.
{'Entries': {'Geometry': {'Geobuf': 'blob'}}}
A batch request for storing geofence geometries into a given geofence collection, or updates the geometry of an existing geofence if a geofence ID is included in the request.
See also: AWS API Documentation
Request Syntax
client.batch_put_geofence(
CollectionName='string',
Entries=[
{
'GeofenceId': 'string',
'Geometry': {
'Polygon': [
[
[
123.0,
],
],
],
'Circle': {
'Center': [
123.0,
],
'Radius': 123.0
},
'Geobuf': b'bytes'
},
'GeofenceProperties': {
'string': 'string'
}
},
]
)
string
[REQUIRED]
The geofence collection storing the geofences.
list
[REQUIRED]
The batch of geofences to be stored in a geofence collection.
(dict) --
Contains geofence geometry details.
GeofenceId (string) -- [REQUIRED]
The identifier for the geofence to be stored in a given geofence collection.
Geometry (dict) -- [REQUIRED]
Contains the details to specify the position of the geofence. Can be a polygon, a circle or a polygon encoded in Geobuf format. Including multiple selections will return a validation error.
Note
The geofence polygon format supports a maximum of 1,000 vertices. The Geofence geobuf format supports a maximum of 100,000 vertices.
Polygon (list) --
A polygon is a list of linear rings which are each made up of a list of vertices.
Each vertex is a 2-dimensional point of the form: [longitude, latitude] . This is represented as an array of doubles of length 2 (so [double, double] ).
An array of 4 or more vertices, where the first and last vertex are the same (to form a closed boundary), is called a linear ring. The linear ring vertices must be listed in counter-clockwise order around the ring’s interior. The linear ring is represented as an array of vertices, or an array of arrays of doubles ( [[double, double], ...] ).
A geofence consists of a single linear ring. To allow for future expansion, the Polygon parameter takes an array of linear rings, which is represented as an array of arrays of arrays of doubles ( [[[double, double], ...], ...] ).
A linear ring for use in geofences can consist of between 4 and 1,000 vertices.
(list) --
(list) --
(float) --
Circle (dict) --
A circle on the earth, as defined by a center point and a radius.
Center (list) -- [REQUIRED]
A single point geometry, specifying the center of the circle, using WGS 84 coordinates, in the form [longitude, latitude] .
(float) --
Radius (float) -- [REQUIRED]
The radius of the circle in meters. Must be greater than zero and no larger than 100,000 (100 kilometers).
Geobuf (bytes) --
Geobuf is a compact binary encoding for geographic data that provides lossless compression of GeoJSON polygons. The Geobuf must be Base64-encoded.
A polygon in Geobuf format can have up to 100,000 vertices.
GeofenceProperties (dict) --
Associates one of more properties with the geofence. A property is a key-value pair stored with the geofence and added to any geofence event triggered with that geofence.
Format: "key" : "value"
(string) --
(string) --
dict
Response Syntax
{
'Successes': [
{
'GeofenceId': 'string',
'CreateTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1)
},
],
'Errors': [
{
'GeofenceId': 'string',
'Error': {
'Code': 'AccessDeniedError'|'ConflictError'|'InternalServerError'|'ResourceNotFoundError'|'ThrottlingError'|'ValidationError',
'Message': 'string'
}
},
]
}
Response Structure
(dict) --
Successes (list) --
Contains each geofence that was successfully stored in a geofence collection.
(dict) --
Contains a summary of each geofence that was successfully stored in a given geofence collection.
GeofenceId (string) --
The geofence successfully stored in a geofence collection.
CreateTime (datetime) --
The timestamp for when the geofence was stored in a geofence collection in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
UpdateTime (datetime) --
The timestamp for when the geofence was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
Errors (list) --
Contains additional error details for each geofence that failed to be stored in a geofence collection.
(dict) --
Contains error details for each geofence that failed to be stored in a given geofence collection.
GeofenceId (string) --
The geofence associated with the error message.
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.
{'Geometry': {'Geobuf': 'blob'}}
Retrieves the geofence details from a geofence collection.
Note
The returned geometry will always match the geometry format used when the geofence was created.
See also: AWS API Documentation
Request Syntax
client.get_geofence(
CollectionName='string',
GeofenceId='string'
)
string
[REQUIRED]
The geofence collection storing the target geofence.
string
[REQUIRED]
The geofence you're retrieving details for.
dict
Response Syntax
{
'GeofenceId': 'string',
'Geometry': {
'Polygon': [
[
[
123.0,
],
],
],
'Circle': {
'Center': [
123.0,
],
'Radius': 123.0
},
'Geobuf': b'bytes'
},
'Status': 'string',
'CreateTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1),
'GeofenceProperties': {
'string': 'string'
}
}
Response Structure
(dict) --
GeofenceId (string) --
The geofence identifier.
Geometry (dict) --
Contains the geofence geometry details describing a polygon or a circle.
Polygon (list) --
A polygon is a list of linear rings which are each made up of a list of vertices.
Each vertex is a 2-dimensional point of the form: [longitude, latitude] . This is represented as an array of doubles of length 2 (so [double, double] ).
An array of 4 or more vertices, where the first and last vertex are the same (to form a closed boundary), is called a linear ring. The linear ring vertices must be listed in counter-clockwise order around the ring’s interior. The linear ring is represented as an array of vertices, or an array of arrays of doubles ( [[double, double], ...] ).
A geofence consists of a single linear ring. To allow for future expansion, the Polygon parameter takes an array of linear rings, which is represented as an array of arrays of arrays of doubles ( [[[double, double], ...], ...] ).
A linear ring for use in geofences can consist of between 4 and 1,000 vertices.
(list) --
(list) --
(float) --
Circle (dict) --
A circle on the earth, as defined by a center point and a radius.
Center (list) --
A single point geometry, specifying the center of the circle, using WGS 84 coordinates, in the form [longitude, latitude] .
(float) --
Radius (float) --
The radius of the circle in meters. Must be greater than zero and no larger than 100,000 (100 kilometers).
Geobuf (bytes) --
Geobuf is a compact binary encoding for geographic data that provides lossless compression of GeoJSON polygons. The Geobuf must be Base64-encoded.
A polygon in Geobuf format can have up to 100,000 vertices.
Status (string) --
Identifies the state of the geofence. A geofence will hold one of the following states:
ACTIVE — The geofence has been indexed by the system.
PENDING — The geofence is being processed by the system.
FAILED — The geofence failed to be indexed by the system.
DELETED — The geofence has been deleted from the system index.
DELETING — The geofence is being deleted from the system index.
CreateTime (datetime) --
The timestamp for when the geofence collection was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
UpdateTime (datetime) --
The timestamp for when the geofence collection was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
GeofenceProperties (dict) --
User defined properties of the geofence. A property is a key-value pair stored with the geofence and added to any geofence event triggered with that geofence.
Format: "key" : "value"
(string) --
(string) --
{'Entries': {'Geometry': {'Geobuf': 'blob'}}}
Lists geofences stored in a given geofence collection.
See also: AWS API Documentation
Request Syntax
client.list_geofences(
CollectionName='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The name of the geofence collection storing the list of geofences.
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
integer
An optional limit for the number of geofences returned in a single call.
Default value: 100
dict
Response Syntax
{
'Entries': [
{
'GeofenceId': 'string',
'Geometry': {
'Polygon': [
[
[
123.0,
],
],
],
'Circle': {
'Center': [
123.0,
],
'Radius': 123.0
},
'Geobuf': b'bytes'
},
'Status': 'string',
'CreateTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1),
'GeofenceProperties': {
'string': 'string'
}
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Entries (list) --
Contains a list of geofences stored in the geofence collection.
(dict) --
Contains a list of geofences stored in a given geofence collection.
Note
The returned geometry will always match the geometry format used when the geofence was created.
GeofenceId (string) --
The geofence identifier.
Geometry (dict) --
Contains the geofence geometry details describing a polygon or a circle.
Polygon (list) --
A polygon is a list of linear rings which are each made up of a list of vertices.
Each vertex is a 2-dimensional point of the form: [longitude, latitude] . This is represented as an array of doubles of length 2 (so [double, double] ).
An array of 4 or more vertices, where the first and last vertex are the same (to form a closed boundary), is called a linear ring. The linear ring vertices must be listed in counter-clockwise order around the ring’s interior. The linear ring is represented as an array of vertices, or an array of arrays of doubles ( [[double, double], ...] ).
A geofence consists of a single linear ring. To allow for future expansion, the Polygon parameter takes an array of linear rings, which is represented as an array of arrays of arrays of doubles ( [[[double, double], ...], ...] ).
A linear ring for use in geofences can consist of between 4 and 1,000 vertices.
(list) --
(list) --
(float) --
Circle (dict) --
A circle on the earth, as defined by a center point and a radius.
Center (list) --
A single point geometry, specifying the center of the circle, using WGS 84 coordinates, in the form [longitude, latitude] .
(float) --
Radius (float) --
The radius of the circle in meters. Must be greater than zero and no larger than 100,000 (100 kilometers).
Geobuf (bytes) --
Geobuf is a compact binary encoding for geographic data that provides lossless compression of GeoJSON polygons. The Geobuf must be Base64-encoded.
A polygon in Geobuf format can have up to 100,000 vertices.
Status (string) --
Identifies the state of the geofence. A geofence will hold one of the following states:
ACTIVE — The geofence has been indexed by the system.
PENDING — The geofence is being processed by the system.
FAILED — The geofence failed to be indexed by the system.
DELETED — The geofence has been deleted from the system index.
DELETING — The geofence is being deleted from the system index.
CreateTime (datetime) --
The timestamp for when the geofence was stored in a geofence collection in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
UpdateTime (datetime) --
The timestamp for when the geofence was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
GeofenceProperties (dict) --
User defined properties of the geofence. A property is a key-value pair stored with the geofence and added to any geofence event triggered with that geofence.
Format: "key" : "value"
(string) --
(string) --
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.
{'Geometry': {'Geobuf': 'blob'}}
Stores a geofence geometry in a given geofence collection, or updates the geometry of an existing geofence if a geofence ID is included in the request.
See also: AWS API Documentation
Request Syntax
client.put_geofence(
CollectionName='string',
GeofenceId='string',
Geometry={
'Polygon': [
[
[
123.0,
],
],
],
'Circle': {
'Center': [
123.0,
],
'Radius': 123.0
},
'Geobuf': b'bytes'
},
GeofenceProperties={
'string': 'string'
}
)
string
[REQUIRED]
The geofence collection to store the geofence in.
string
[REQUIRED]
An identifier for the geofence. For example, ExampleGeofence-1 .
dict
[REQUIRED]
Contains the details to specify the position of the geofence. Can be a polygon, a circle or a polygon encoded in Geobuf format. Including multiple selections will return a validation error.
Note
The geofence polygon format supports a maximum of 1,000 vertices. The Geofence Geobuf format supports a maximum of 100,000 vertices.
Polygon (list) --
A polygon is a list of linear rings which are each made up of a list of vertices.
Each vertex is a 2-dimensional point of the form: [longitude, latitude] . This is represented as an array of doubles of length 2 (so [double, double] ).
An array of 4 or more vertices, where the first and last vertex are the same (to form a closed boundary), is called a linear ring. The linear ring vertices must be listed in counter-clockwise order around the ring’s interior. The linear ring is represented as an array of vertices, or an array of arrays of doubles ( [[double, double], ...] ).
A geofence consists of a single linear ring. To allow for future expansion, the Polygon parameter takes an array of linear rings, which is represented as an array of arrays of arrays of doubles ( [[[double, double], ...], ...] ).
A linear ring for use in geofences can consist of between 4 and 1,000 vertices.
(list) --
(list) --
(float) --
Circle (dict) --
A circle on the earth, as defined by a center point and a radius.
Center (list) -- [REQUIRED]
A single point geometry, specifying the center of the circle, using WGS 84 coordinates, in the form [longitude, latitude] .
(float) --
Radius (float) -- [REQUIRED]
The radius of the circle in meters. Must be greater than zero and no larger than 100,000 (100 kilometers).
Geobuf (bytes) --
Geobuf is a compact binary encoding for geographic data that provides lossless compression of GeoJSON polygons. The Geobuf must be Base64-encoded.
A polygon in Geobuf format can have up to 100,000 vertices.
dict
Associates one of more properties with the geofence. A property is a key-value pair stored with the geofence and added to any geofence event triggered with that geofence.
Format: "key" : "value"
(string) --
(string) --
dict
Response Syntax
{
'GeofenceId': 'string',
'CreateTime': datetime(2015, 1, 1),
'UpdateTime': datetime(2015, 1, 1)
}
Response Structure
(dict) --
GeofenceId (string) --
The geofence identifier entered in the request.
CreateTime (datetime) --
The timestamp for when the geofence was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
UpdateTime (datetime) --
The timestamp for when the geofence was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ