Requirements Parameters Examples See also

Location

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

Note

This action isn't available in China.

Requirements

This rule action has the following requirements:

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

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

Parameters

When you create an Amazon 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 Amazon 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 Amazon CLI only

Examples

The following JSON example defines a Location action in an Amazon 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 Amazon 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"
		}
	]
}