geofences

Creates, updates, deletes, gets or lists a geofences resource.

Overview

Name	geofences
Type	Resource
Id	aws.location.geofences

Fields

The following fields are returned by SELECT queries:

get_geofence

Name	Datatype	Description
create_time	string (date-time)	The timestamp for when the geofence collection was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
geofence_id	string	The geofence identifier. (pattern: <code>[-._\p{L}\p{N}]+</code>)
geofence_properties	object	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"
geometry	object	Contains the geofence geometry details describing the position of the geofence. Can be a circle, a polygon, or a multipolygon.
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.
update_time	string (date-time)	The timestamp for when the geofence collection was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ

list_geofences

Name	Datatype	Description
create_time	string (date-time)	The timestamp for when the geofence was stored in a geofence collection in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ
geofence_id	string	The geofence identifier. (pattern: <code>[-._\p{L}\p{N}]+</code>)
geofence_properties	object	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"
geometry	object	Contains the geofence geometry details. A geofence geometry can be a circle, a polygon, or a multipolygon. Polygon and MultiPolygon geometries can be defined using their respective parameters, or encoded in Geobuf format using the Geobuf parameter. Including multiple geometry types in the same request will return a validation error. Amazon Location doesn't currently support polygons that cross the antimeridian.
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.
update_time	string (date-time)	The timestamp for when the geofence was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_geofence	select	collection_name, geofence_id, region		Retrieves the geofence details from a geofence collection. The returned geometry will always match the geometry format used when the geofence was created.
list_geofences	select	collection_name, region		Lists geofences stored in a given geofence collection.
put_geofence	replace	collection_name, geofence_id, region		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.
batch_delete_geofence	exec	collection_name, region, GeofenceIds		Deletes a batch of geofences from a geofence collection. This operation deletes the resource permanently.
batch_evaluate_geofences	exec	collection_name, region, DevicePositionUpdates		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. The last geofence that a device was observed within is tracked for 30 days after the most recent device position update. Geofence evaluation uses the given device position. It does not account for the optional Accuracy of a DevicePositionUpdate. The DeviceID is used as a string to represent the device. You do not need to have a Tracker associated with the DeviceID.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
collection_name	string	The geofence collection used in evaluating the position of devices against its geofences.
geofence_id	string	An identifier for the geofence. For example, ExampleGeofence-1.
region	string	AWS region (default: us-east-1)

SELECT examples

get_geofence

Retrieves the geofence details from a geofence collection. The returned geometry will always match the geometry format used when the geofence was created.

SELECT
create_time,
geofence_id,
geofence_properties,
geometry,
status,
update_time
FROM aws.location.geofences
WHERE collection_name = '{{ collection_name }}' -- required
AND geofence_id = '{{ geofence_id }}' -- required
AND region = '{{ region }}' -- required
;

list_geofences

Lists geofences stored in a given geofence collection.

SELECT
create_time,
geofence_id,
geofence_properties,
geometry,
status,
update_time
FROM aws.location.geofences
WHERE collection_name = '{{ collection_name }}' -- required
AND region = '{{ region }}' -- required
;

REPLACE examples

put_geofence

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.

REPLACE aws.location.geofences
SET 
Geometry = '{{ Geometry }}',
GeofenceProperties = '{{ GeofenceProperties }}'
WHERE 
collection_name = '{{ collection_name }}' --required
AND geofence_id = '{{ geofence_id }}' --required
AND region = '{{ region }}' --required
RETURNING
create_time,
geofence_id,
update_time;

Lifecycle Methods

batch_delete_geofence

Deletes a batch of geofences from a geofence collection. This operation deletes the resource permanently.

EXEC aws.location.geofences.batch_delete_geofence 
@collection_name='{{ collection_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"GeofenceIds": "{{ GeofenceIds }}"
}'
;

batch_evaluate_geofences

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. The last geofence that a device was observed within is tracked for 30 days after the most recent device position update. Geofence evaluation uses the given device position. It does not account for the optional Accuracy of a DevicePositionUpdate. The DeviceID is used as a string to represent the device. You do not need to have a Tracker associated with the DeviceID.

EXEC aws.location.geofences.batch_evaluate_geofences 
@collection_name='{{ collection_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"DevicePositionUpdates": "{{ DevicePositionUpdates }}"
}'
;