Location

The Location (location) action sends your geographical location data to Amazon Location Service.

Requirements

This rule action has the following requirements:

• An IAM role that AWS IoT can assume to perform the geo:BatchUpdateDevicePosition operation. For more information, see Granting an AWS IoT rule the access it requires.

  In the AWS IoT console, you can choose or create a role to allow AWS IoT to perform this rule action.

Parameters

When you create an AWS IoT rule with this action, you must specify the following information:

deviceId

The unique ID of the device providing the location data. For more information, see DeviceId from the Amazon Location Service API Reference.

Supports substitution templates: Yes

latitude

A string that evaluates to a double value that represents the latitude of the device's location.

Supports substitution templates: Yes

longitude

A string that evaluates to a double value that represents the longitude of the device's location.

Supports substitution templates: Yes

roleArn

The IAM role that allows access to the Amazon Location Service domain. For more information, see Requirements.

timestamp

The time that the location data was sampled. The default value is the time that the MQTT message was processed.

The timestamp value consists of the following two values:

• value: An expression that returns a long epoch time value. You can use the time_to_epoch(String, String) function to create a valid timestamp from a date or time value passed in the message payload. Supports substitution templates: Yes.

• unit: (Optional) The precision of the timestamp value that results from the expression described in value. Valid values: SECONDS | MILLISECONDS | MICROSECONDS | NANOSECONDS. The default is MILLISECONDS. Supports substitution templates: API and AWS CLI only.

trackerName

The name of the tracker resource in Amazon Location in which the location is updated. For more information, see Tracker from the Amazon Location Service Developer Guide.

Supports substitution templates: API and AWS CLI only

Examples

The following JSON example defines a Location action in an AWS IoT rule.

{
	"topicRulePayload": {
		"sql": "SELECT * FROM 'some/topic'",
		"ruleDisabled": false,
		"awsIotSqlVersion": "2016-03-23",
		"actions": [
			{
				"location": {
					"roleArn": "arn:aws:iam::123454962127:role/service-role/ExampleRole",
					"trackerName": "MyTracker",
					"deviceId": "001",
					"sampleTime": {
						"value": "${timestamp()}",
						"unit": "MILLISECONDS"
					},
					"latitude": "-12.3456",
					"longitude": "65.4321"
				}
			}
		]
	}
}

The following JSON example defines a Location action with substitution templates in an AWS IoT rule.

{
	"topicRulePayload": {
		"sql": "SELECT * FROM 'some/topic'",
		"ruleDisabled": false,
		"awsIotSqlVersion": "2016-03-23",
		"actions": [
			{
				"location": {
					"roleArn": "arn:aws:iam::123456789012:role/service-role/ExampleRole",
					"trackerName": "${TrackerName}",
					"deviceId": "${DeviceID}",
					"timestamp": {
						"value": "${timestamp()}",
						"unit": "MILLISECONDS"
					},
					"latitude": "${get(position, 0)}",
					"longitude": "${get(position, 1)}"
				}
			}
		]
	}
}

The following MQTT payload example shows how substitution templates in the preceding example accesses data. You can use the get-device-position-history CLI command to verify that the MQTT payload data is delivered in your location tracker.

{
	"TrackerName": "mytracker",
	"DeviceID": "001",
	"position": [
		"-12.3456",
		"65.4321"
	]
}

aws location get-device-position-history --device-id 001 --tracker-name mytracker

{
	"DevicePositions": [
		{
			"DeviceId": "001",
			"Position": [
				-12.3456,
				65.4321
			],
			"ReceivedTime": "2022-11-11T01:31:54.464000+00:00",
			"SampleTime": "2022-11-11T01:31:54.308000+00:00"
		}
	]
}

See also

• What is Amazon Location Service? in the Amazon Location Service Developer Guide.