# AWS IoT Core Device Location | | | --- | | Before using the AWS IoT Core Device Location feature, review the Terms and Conditions for this feature. Note that AWS may transmit your geolocation search request parameters, such as the location data used to run searches, and other information to your chosen third party data provider, which may be outside of the AWS Region that you are currently using. The third party provider and the solver to be used is chosen based on the input payload received. For more information, see [AWS Service Terms](https://aws.amazon.com/service-terms). | Use AWS IoT Core Device Location to test the location of your IoT devices using third-party solvers. *Solvers* are algorithms provided by third-party vendors that resolve measurement data and estimate the location of your device. By identifying the location of your devices, you can track and debug them in the field to troubleshoot any issues. The measurement data collected from various sources is resolved, and the geolocation information is reported as a [GeoJSON](https://geojson.org/) payload. The GeoJSON format is a format that's used to encode geographic data structures. The payload contains the latitude and longitude coordinates of your device location, which are based on the [ World Geodetic System coordinate system (WGS84)](https://gisgeography.com/wgs84-world-geodetic-system/). **Topics** + [Measurement types and solvers](#location-measurement-types) + [How AWS IoT Core Device Location works](#location-how-works) + [How to use AWS IoT Core Device Location](#location-how-use) + [Resolving location of IoT devices](device-location-resolve-solvers.md) + [Resolving device location using AWS IoT Core Device Location MQTT topics](device-location-reserved-topics.md) + [Location solvers and device payload](device-location-solvers-payload.md) ## Measurement types and solvers AWS IoT Core Device Location partners with third-party vendors to resolve the measurement data and to provide an estimated device location. The following table shows the measurement types and the third-party location solvers, and information about supported devices. For information about LoRaWAN devices and configuring device location for them, see [Configuring position of LoRaWAN resources](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/lorawan-configure-location.html). **Note** General IoT devices and Sidewalk devices can use the device location MQTT topics to obtain the location information. For Wi-Fi, Cellular, and IP address measurement types, if the devices publish the measurement data to the [reserved topics](device-location-reserved-topics.md) in the defined GeoJSON format, AWS IoT Core Device Location can resolve the location of the device. For GNSS measurement type, the device must have the LR11xx chip to scan the measurement data for obtaining the resolved location information using the GNSS solver. For information about obtaining location information for LoRaWAN devices, see [Configuring position for LoRaWAN resources](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/lorawan-configure-location.html) in the *AWS IoT Wireless documentation*. **Measurement types and solvers** | Measurement type | Third-party solvers | Supported devices | | --- | --- | --- | | Wi-Fi access points | Wi-Fi based solver | General IoT devices, LoRaWAN, and Amazon Sidewalk devices | | Cellular radio towers: GSM, LTE, CDMA, SCDMA, WCMDA, and TD-SCDMA data | Cellular based solver | General IoT devices, LoRaWAN, and Amazon Sidewalk devices | | IP address | IP reverse lookup solver | Any IoT device that connects over TCP/IP | | GNSS scan data (NAV messages) | GNSS solver | General IoT devices, LoRaWAN, and Amazon Sidewalk devices | | Bluetooth Low Energy (BLE) | BLE based solver | Amazon Sidewalk devices | For more information about the location solvers and examples that show the device payload for the various measurement types, see [Location solvers and device payload](device-location-solvers-payload.md). ## How AWS IoT Core Device Location works The following diagram shows how AWS IoT Core Device Location collects measurement data and resolves the location information of your devices. ![\[Image showing how AWS IoT Core Device Location uses your raw measurement data and resolves the device location.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/iot-device-location.png) The following steps show how AWS IoT Core Device Location works. 1. **Receive measurement data** The raw measurement data related to your device location is first sent from the device. The measurement data is specified as a JSON payload. 1. **Process measurement data** The measurement data is processed, and AWS IoT Core Device Location chooses the measurement data to be used, which can be Wi-Fi, cellular, GNSS scan, or IP address information. 1. **Choose solver** The third-party solver is chosen based on the measurement data. For example, if the measurement data contains Wi-Fi and IP address information, it chooses the Wi-Fi solver and the IP reverse lookup solver. 1. **Obtain resolved location** An API request is sent to the solver providers requesting to resolve the location. AWS IoT Core Device Location then gets the estimated geolocation information from the solvers. 1. **Choose resolved location** The resolved location information and its accuracy is compared, and AWS IoT Core Device Location chooses the geolocation results with the highest accuracy. 1. **Output location information** The geolocation information is sent to you as a GeoJSON payload. The payload contains the WGS84 geo coordinates, the accuracy information, confidence levels, and the timestamp at which the resolved location was obtained. ## How to use AWS IoT Core Device Location The following steps show how to use AWS IoT Core Device Location. 1. **Provide measurement data** Specify the raw measurement data related to the location of your device as a JSON payload. To retrieve the payload measurement data, go to your device logs, or use CloudWatch Logs, and copy the payload data information. The JSON payload must contain one or more types of data measurement. For examples that show the payload format for various solvers, see [Location solvers and device payload](device-location-solvers-payload.md). 1. **Resolve location information** Using the [Device Location](https://console.aws.amazon.com/iot/home#/device-location-test) page in the AWS IoT console or the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation, pass the payload measurement data and resolve the device location. AWS IoT Core Device Location then chooses the solver with the highest accuracy and reports the device location. For more information, see [Resolving location of IoT devices](device-location-resolve-solvers.md). 1. **Copy location information** Verify the geolocation information that was resolved by AWS IoT Core Device Location and reported as a GeoJSON payload. You can copy the payload for use with your applications and other AWS services. For example, you can send your geographical location data to Amazon Location Service using the [Location](location-rule-action.md) AWS IoT rule action. The following topics show how to use AWS IoT Core Device Location and examples of device location payload. + [Resolving location of IoT devices](device-location-resolve-solvers.md) + [Location solvers and device payload](device-location-solvers-payload.md) # Resolving location of IoT devices Use AWS IoT Core Device Location to decode the measurement data from your devices, and resolve the device location using third-party solvers. The resolved location is generated as a GeoJSON payload with the geo coordinates and accuracy information. You can resolve the location of your device from the AWS IoT console, the AWS IoT Wireless API, or AWS CLI. **Topics** + [Resolving device location (console)](#location-resolve-console) + [Resolving device location (API)](#location-resolve-api) + [Troubleshooting errors when resolving the location](#location-resolve-troubleshoot) ## Resolving device location (console) To resolve the device location (console) 1. Go to the [Device Location](https://console.aws.amazon.com/iot/home#/device-location-test) page in the AWS IoT console. 1. Obtain the payload measurement data from your device logs or from CloudWatch Logs, and enter it in the **Resolve position via payload** section. The following code shows a sample JSON payload. The payload contains cellular and Wi-Fi measurement data. If your payload contains additional types of measurement data, the solver with the best accuracy will be used. For more information and payload examples, see [Location solvers and device payload](device-location-solvers-payload.md). **Note** The JSON payload must contain at least one type of measurement data. ``` { "Timestamp": 1664313161, "Ip":{ "IpAddress": "54.240.198.35" }, "WiFiAccessPoints": [{ "MacAddress": "A0:EC:F9:1E:32:C1", "Rss": -77 }], "CellTowers": { "Gsm": [{ "Mcc": 262, "Mnc": 1, "Lac": 5126, "GeranCid": 16504, "GsmLocalId": { "Bsic": 6, "Bcch": 82 }, "GsmTimingAdvance": 1, "RxLevel": -110, "GsmNmr": [{ "Bsic": 7, "Bcch": 85, "RxLevel": -100, "GlobalIdentity": { "Lac": 1, "GeranCid": 1 } }] }], "Wcdma": [{ "Mcc": 262, "Mnc": 7, "Lac": 65535, "UtranCid": 14674663, "WcdmaNmr": [{ "Uarfcndl": 10786, "UtranCid": 14674663, "Psc": 149 }, { "Uarfcndl": 10762, "UtranCid": 14674663, "Psc": 211 } ] }], "Lte": [{ "Mcc": 262, "Mnc": 2, "EutranCid": 2898945, "Rsrp": -50, "Rsrq": -5, "LteNmr": [{ "Earfcn": 6300, "Pci": 237, "Rsrp": -60, "Rsrq": -6, "EutranCid": 2898945 }, { "Earfcn": 6300, "Pci": 442, "Rsrp": -70, "Rsrq": -7, "EutranCid": 2898945 } ] }] } } ``` 1. To resolve the location information, choose **Resolve**. The location information is of type blob and returned as a payload that uses the GeoJSON format, which is a format used for encoding geographical data structures. The payload contains: + The WGS84 geo coordinates, which include the latitude and longitude information. It might also include an altitude information. + The type of location information reported, such as **Point**. A point location type represents the location as a WGS84 latitude and longitude, encoded as a [GeoJSON point](https://geojson.org/geojson-spec.html#point). + The horizontal and vertical accuracy information, which indicates the difference, in meters, between the location information estimated by the solvers and the actual device location. + The confidence level, which indicates the uncertainty in the location estimate response. The default value is 0.68, which indicates a 68% probability that the actual device location is within the uncertainty radius of the estimated location. + The city, state, country, and postal code where the device is located. This information will be reported only when the IP reverse lookup solver is used. + The timestamp information, which corresponds to the date and time at which the location was resolved. It uses the Unix timestamp format. The following code shows a sample GeoJSON payload returned by resolving the location. **Note** If AWS IoT Core Device Location reports errors when attempting to resolve the location, you can troubleshoot the errors and resolve the location. For more information, see [Troubleshooting errors when resolving the location](#location-resolve-troubleshoot). ``` { "coordinates": [ 13.376076698303223, 52.51823043823242 ], "type": "Point", "properties": { "verticalAccuracy": 45, "verticalConfidenceLevel": 0.68, "horizontalAccuracy": 303, "horizontalConfidenceLevel": 0.68, "country": "USA", "state": "CA", "city": "Sunnyvalue", "postalCode": "91234", "timestamp": "2022-11-18T12:23:58.189Z" } } ``` 1. Go to the **Resource location** section and verify the geolocation information reported by AWS IoT Core Device Location . You can copy the payload for use with other applications and AWS services. For example, you can use the [Location](location-rule-action.md) to send your geographical location data to Amazon Location Service. ## Resolving device location (API) To resolve the device location using the AWS IoT Wireless API, use the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation or the [get-position-estimate](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-position-estimate.html) CLI command. Specify the payload measurement data as input, and run the API operation to resolve the device location. **Note** The `GetPositionEstimate` API operation doesn't store any device or state information and can't be used retrieve historical location data. It performs a one-time operation that resolves the measurement data and produces the estimated location. To retrieve the location information, you must specify the payload information every time you perform this API operation. The following command shows an example of how to resolve the location using this API operation. **Note** When running the `get-position-estimate` CLI command, you must specify the output JSON file as the first input. This JSON file will store the estimated location information obtained as response from the CLI in GeoJSON format. For example, the following command stores the location information in the *locationout.json* file. ``` aws iotwireless get-position-estimate locationout.json \ --ip IpAddress=""54.240.198.35"" \ --wi-fi-access-points \ MacAddress="A0:EC:F9:1E:32:C1",Rss=-75 \ MacAddress="A0:EC:F9:15:72:5E",Rss=-67 ``` This example includes both Wi-Fi access points and IP address as the measurement types. AWS IoT Core Device Location chooses between the Wi-Fi solver and the IP reverse lookup solver, and it selects the solver with the higher accuracy. The resolved location is returned as a payload that uses the GeoJSON format, which is a format used for encoding geographical data structures. It is then stored in the *locationout.json* file. The payload contains the WGS84 latitude and longitude coordinates, accuracy and confidence level information, the location data type, and the timestamp at which the location was resolved. ``` { "coordinates": [ 13.37704086303711, 52.51865005493164 ], "type": "Point", "properties": { "verticalAccuracy": 707, "verticalConfidenceLevel": 0.68, "horizontalAccuracy": 389, "horizontalConfidenceLevel": 0.68, "country": "USA", "state": "CA", "city": "Sunnyvalue", "postalCode": "91234", "timestamp": "2022-11-18T14:03:57.391Z" } } ``` ## Troubleshooting errors when resolving the location When you attempt to resolve the location, you might see any of the following error codes. AWS IoT Core Device Location might generate an error when using the `GetPositionEstimate` API operation, or else refer to the line number corresponding to the error in the AWS IoT console. + **400 error** This error indicates that the format of the device payload JSON can't be validated by AWS IoT Core Device Location. The error might occur because: + The JSON measurement data is formatted incorrectly. + The payload contains only the timestamp information. + The measurement data parameters, such as the IP address, are not valid. To resolve this error, check whether your JSON is formatted correctly and contains data from one or more measurement types as input. If the IP address is invalid, for information about how you can provide a valid IP address to resolve the error, see [IP reverse lookup solver](device-location-solvers-payload.md#location-solvers-ip). + **403 error** This error indicates that you don't have the permissions to perform the API operation or to use the AWS IoT console to retrieve the device location. To resolve this error, verify that you have the required permissions to perform this action. This error might occur if your AWS Management Console session or your AWS CLI session token have expired. To resolve this error, refresh the session token to use the AWS CLI, or log out of the AWS Management Console and then log in using your credentials. + **404 error** This error indicates that no location information was found or solved by AWS IoT Core Device Location. The error might occur due to cases such as insufficient data in the measurement data input. For example: + The MAC address or cellular tower information is not sufficient. + The IP address is not available to look up and retrieve the location. + The GNSS payload is not sufficient. To resolve the error in such cases, check whether your measurement data contains sufficient information required to resolve the device location. + **500 error** This error indicates that an internal server exception occurred when AWS IoT Core Device Location attempted to resolve the location. To attempt to fix this error, refresh the session and retry sending the measurement data to be resolved. # Resolving device location using AWS IoT Core Device Location MQTT topics You can use reserved MQTT topics to get the latest location information for your devices with the AWS IoT Core Device Location feature. ## Format of device location MQTT topics Reserved topics for AWS IoT Core Device Location use the following prefix: `$aws/device_location/{customer_device_id}/` To create a complete topic, first replace `customer_device_id` with your unique ID that you use for identifying your device. We recommend that you specify the `WirelessDeviceId`, such as for LoRaWAN and Sidewalk devices, and `thingName`, if your device is registered as an AWS IoT thing. You then append the topic with the topic stub, such as `get_position_estimate` or `get_position_estimate/accepted` as shown in the following section. **Note** The `{customer_device_id}` can only contain letters, numbers, and dashes. When subscribing to device location topics, you can only use the plus sign (\$1) as a wildcard character. For example, you can use the `+` wildcard for the `{customer_device_id}` to obtain the location information for your devices. When you subscribe to the topic `$aws/device_location/+/get_position_estimate/accepted`, a message will be published with the location information for devices that match any device ID if it was successfully resolved. The following are the reserved topics used to interact with AWS IoT Core Device Location. **Device location MQTT topics** | Topic | Allowed operations | Description | | --- | --- | --- | | \$1aws/device\$1location/*customer\$1device\$1id*/get\$1position\$1estimate | Publish | A device publishes to this topic to get the scanned raw measurement data to be resolved by AWS IoT Core Device Location. | | \$1aws/device\$1location/*customer\$1device\$1id*/get\$1position\$1estimate/accepted | Subscribe | AWS IoT Core Device Location publishes the location information to this topic when it successfully resolves the device location. | | \$1aws/device\$1location/*customer\$1device\$1id*/get\$1position\$1estimate/rejected | Subscribe | AWS IoT Core Device Location publishes the error information to this topic when it fails to resolve the device location. | ## Policy for device location MQTT topics To receive messages from device location topics, your device must use a policy that allows it to connect to the AWS IoT device gateway and subscribe to the MQTT topics. The following is an example of the policy required for receiving messages for the various topics. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate/accepted", "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/accepted", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/rejected" ] } ] } ``` ## Device location topics and payload The following shows the AWS IoT Core Device Location topics, the format of their message payload, and an example policy for each topic. **Topics** + [/get\$1position\$1estimate](#get-position-estimate) + [/get\$1position\$1estimate/accepted](#get-position-estimate-accepted) + [/get\$1position\$1estimate/rejected](#get-position-estimate-rejected) ### /get\$1position\$1estimate Publish a message to this topic to get the raw measurement data from the device to be resolved by AWS IoT Core Device Location. ``` $aws/device_location/customer_device_id/get_position_estimate ``` AWS IoT Core Device Location responds by publishing to either [/get\$1position\$1estimate/accepted](#get-position-estimate-accepted) or [/get\$1position\$1estimate/rejected](#get-position-estimate-rejected). **Note** The message published to this topic must be a valid JSON payload. If the input message is not in valid JSON format, you won't get any response. For more information, see [Message payload](#get-position-estimate-payload). #### Message payload The message payload format follows a similar structure as the AWS IoT Wireless API operation request body, [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html). It contains: + An optional `Timestamp` string, which corresponds to the date and time the location was resolved. The `Timestamp` string can have a minimum length of 1 and maximum length of 10. + An optional `MessageId` string, which can be used to map the request to the response. If you specify this string, the message published to the `get_position_estimate/accepted` or `get_position_estimate/rejected` topics will contain this `MessageId`. The `MessageID` string can have a minimum length of 1 and maximum length of 256. + The measurement data from the device that contains one or more of the following measurement types: + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_WiFiAccessPoint.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_WiFiAccessPoint.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CellTowers.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CellTowers.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Ip.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Ip.html) + [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Gnss.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Gnss.html) The following shows a sample message payload. ``` { "Timestamp": "1664313161", "MessageId": "ABCD1", "WiFiAccessPoints": [ { "MacAddress": "A0:EC:F9:1E:32:C1", "Rss": -66 } ], "Ip":{ "IpAddress": "54.192.168.0" }, "Gnss":{ "Payload":"8295A614A2029517F4F77C0A7823B161A6FC57E25183D96535E3689783F6CA48", "CaptureTime":1354393948 } } ``` #### Example policy The following is an example of the required policy: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate" ] } ] } ``` ### /get\$1position\$1estimate/accepted AWS IoT Core Device Location publishes a response to this topic when returning the resolved location information for your device. The location information is returned in [GeoJSON format](https://geojson.org/). ``` $aws/device_location/customer_device_id/get_position_estimate/accepted ``` The following shows the message payload and an example policy. #### Message payload The following is an example of the message payload in GeoJSON format. If you specified a `MessageId` in your raw measurement data and AWS IoT Core Device Location resolved the location information successfully, then the message payload returns the same `MessageId` information. ``` { "coordinates": [ 13.37704086303711, 52.51865005493164 ], "type": "Point", "properties": { "verticalAccuracy": 707, "verticalConfidenceLevel": 0.68, "horizontalAccuracy": 389, "horizontalConfidenceLevel": 0.68, "country": "USA", "state": "CA", "city": "Sunnyvalue", "postalCode": "91234", "timestamp": "2022-11-18T14:03:57.391Z", "messageId": "ABCD1" } } ``` #### Example policy The following is an example of the required policy: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate/accepted" ] } ] } ``` ### /get\$1position\$1estimate/rejected AWS IoT Core Device Location publishes an error response to this topic when it fails to resolve the device location. ``` $aws/device_location/customer_device_id/get_position_estimate/rejected ``` The following shows the message payload and example policy. For information about the errors, see [Troubleshooting errors when resolving the location](device-location-resolve-solvers.md#location-resolve-troubleshoot). #### Message payload The following is an example of the message payload that provides the error code and message, which indicates why AWS IoT Core Device Location failed to resolve the location information. If you specified a `MessageId` when providing your raw measurement data and AWS IoT Core Device Location failed to resolve the location information, then the same `MessageId` information will be returned in the message payload. ``` { "errorCode": 500, "errorMessage":"Internal server error", "messageId": "ABCD1" } ``` #### Example policy The following is an example of the required policy: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/device_location/device-123/get_position_estimate/rejected" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/device_location/device-123/get_position_estimate/rejected" ] } ] } ``` # Location solvers and device payload Location solvers are algorithms that can be used to resolve the location of your IoT devices. AWS IoT Core Device Location supports the following location solvers. You'll see examples of the JSON payload format for these measurement types, the devices supported by the solver, and how the location is resolved. To resolve the device location, specify one or more of these measurement data types. A single, resolved location will be returned for all measurement data combined. **Topics** + [Wi-Fi based solver](#location-solvers-wifi) + [Cellular based solver](#location-solvers-cellular) + [IP reverse lookup solver](#location-solvers-ip) + [GNSS solver](#location-solvers-gnss) + [BLE solver for Amazon Sidewalk enabled devices](#location-solvers-ble) ## Wi-Fi based solver Use the Wi-Fi based solver to resolve the location using the scan information from Wi-Fi access points. The solver supports the WLAN technology, and it can be used to compute the device location for general IoT devices connecting over TCP/IP, LoRaWAN wireless devices, and Amazon Sidewalk enabled devices. The LoRaWAN devices must have the LoRa Edge chipset, which can decode the incoming Wi-Fi scan information. LoRa Edge is an ultra-low power platform that integrates a long-range LoRa transceiver, multi-constellation GNSS scanner, and passive Wi-Fi MAC scanner targeting geolocation applications. When an uplink message is received from the device, the Wi-Fi scan data is sent to AWS IoT Core Device Location, and the location is estimated based on the Wi-Fi scan results. The decoded information is then passed to the Wi-Fi based solver to retrieve the location information. To learn more about resolving location data for Amazon Sidewalk enabled devices, visit [AWS IoT Core for Amazon Sidewalk developer guide](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-sidewalk.html). ### Wi-Fi based solver payload example The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives this data as input, it sends an HTTP request to the solver provider to resolve the location information. To retrieve the information, specify values for the MAC Address and RSS (received signal strength). To do this, either provide the JSON payload using this format, or use the [WiFiAccessPoints object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_WiFiAccessPoint.html) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. ``` { "Timestamp": 1664313161, // optional "WiFiAccessPoints": [ { "MacAddress": "A0:EC:F9:1E:32:C1", // required "Rss": -75 // required } ] } ``` ## Cellular based solver You can use the cellular based solver to resolve the location using measurement data obtained from cellular radio towers. The solver supports the following technologies. A single resolved location information is obtained, even if you include measurement data from any or all of these technologies. + GSM + CDMA + WCDMA + TD-SCDMA + LTE ### Cellular based solver payload examples The following code shows examples of the JSON payload from the device that contains cellular measurement data. When AWS IoT Core Device Location receives this data as input, it sends an HTTP request to the solver provider to resolve the location information. To retrieve the information, you either provide the JSON payload using this format in the console, or specify values for the [CellTowers](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-CellTowers) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. You can provide the measurement data by specifying values for parameters using any or all of these cellular technologies. #### LTE (Long-term evolution) When you use this measurement data, you must specify information such as the network and country code of the mobile network, and optional additional parameters including information about the local ID. The following code shows an example of the payload format. For more information about these parameters, see [LTE object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_LteObj.html). ``` { "Timestamp": 1664313161, // optional "CellTowers": { "Lte": [ { "Mcc": int, // required "Mnc": int, // required "EutranCid": int, // required. Make sure that you use int for EutranCid. "Tac": int, // optional "LteLocalId": { // optional "Pci": int, // required "Earfcn": int, // required }, "LteTimingAdvance": int, // optional "Rsrp": int, // optional "Rsrq": float, // optional "NrCapable": boolean, // optional "LteNmr": [ // optional { "Pci": int, // required "Earfcn": int, // required "EutranCid": int, // required "Rsrp": int, // optional "Rsrq": float // optional } ] } ] } } ``` #### GSM (Global System for Mobile Communications) When you use this measurement data, you must specify information such as the network and country code of the mobile network, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [GSM object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GsmObj.html). ``` { "Timestamp": 1664313161, // optional "CellTowers": { "Gsm": [ { "Mcc": int, // required "Mnc": int, // required "Lac": int, // required "GeranCid": int, // required "GsmLocalId": { // optional "Bsic": int, // required "Bcch": int, // required }, "GsmTimingAdvance": int, // optional "RxLevel": int, // optional "GsmNmr": [ // optional { "Bsic": int, // required "Bcch": int, // required "RxLevel": int, // optional "GlobalIdentity": { "Lac": int, // required "GeranCid": int // required } } ] } ] } ``` #### CDMA (Code-division multiple access) When you use this measurement data, you must specify information such as the signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CdmaObj.html). ``` { "Timestamp": 1664313161, // optional "CellTowers": { "Cdma": [ { "SystemId": int, // required "NetworkId": int, // required "BaseStationId": int, // required "RegistrationZone": int, // optional "CdmaLocalId": { // optional "PnOffset": int, // required "CdmaChannel": int, // required }, "PilotPower": int, // optional "BaseLat": float, // optional "BaseLng": float, // optional "CdmaNmr": [ // optional { "PnOffset": int, // required "CdmaChannel": int, // required "PilotPower": int, // optional "BaseStationId": int // optional } ] } ] } } ``` #### WCDMA (Wideband code-division multiple access) When you use this measurement data, you must specify information such as the network and country code, signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CdmaObj.html). ``` { "Timestamp": 1664313161, // optional "CellTowers": { "Wcdma": [ { "Mcc": int, // required "Mnc": int, // required "UtranCid": int, // required "Lac": int, // optional "WcdmaLocalId": { // optional "Uarfcndl": int, // required "Psc": int, // required }, "Rscp": int, // optional "Pathloss": int, // optional "WcdmaNmr": [ // optional { "Uarfcndl": int, // required "Psc": int, // required "UtranCid": int, // required "Rscp": int, // optional "Pathloss": int, // optional } ] } ] } } ``` #### TD-SCDMA (Time division synchronous code-division multiple access) When you use this measurement data, you must specify information such as the network and country code, signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CdmaObj.html). ``` { "Timestamp": 1664313161, // optional "CellTowers": { "Tdscdma": [ { "Mcc": int, // required "Mnc": int, // required "UtranCid": int, // required "Lac": int, // optional "TdscdmaLocalId": { // optional "Uarfcn": int, // required "CellParams": int, // required }, "TdscdmaTimingAdvance": int, // optional "Rscp": int, // optional "Pathloss": int, // optional "TdscdmaNmr": [ // optional { "Uarfcn": int, // required "CellParams": int, // required "UtranCid": int, // optional "Rscp": int, // optional "Pathloss": int, // optional } ] } ] } } ``` ## IP reverse lookup solver You can use the IP reverse lookup solver to resolve the location using the IP address as input. The solver can obtain the location information from devices that have been provisioned with AWS IoT. Specify the IP address information using a format that's either the IPv4 or IPv6 standard pattern, or the IPv6 hex compressed pattern. You then obtain the resolved location estimate, including additional information such as city and country where the device is located. **Note** By using the IP reverse lookup, you agree not to use it for the purpose of identifying or locating a specific household or street address. ### IP reverse lookup solver payload example The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives the IP address information in the measurement data, it looks up this information in the solver provider's database, which is then used to resolve the location information. To retrieve the information, either provide the JSON payload using this format, or specify values for the [Ip](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-Ip) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. **Note** When this solver is used, the city, state, country, and postal code where the device is located is also reported in addition to the coordinates. For an example, see [Resolving device location (console)](device-location-resolve-solvers.md#location-resolve-console). ``` { "Timestamp": 1664313161, "Ip":{ "IpAddress":"54.240.198.35" } } ``` ## GNSS solver Use the GNSS (Global Navigation Satellite System) solver to retrieve the device location using the information contained in the GNSS scan result messages or NAV messages. You can optionally provide additional GNSS assistance information, which reduces the number of variables that the solver must use to search for signals. By providing this assistance information, which includes the position, altitude, and the capture time and accuracy information, the solver can easily identify the satellites in view and compute the device location. This solver can be used with LoRaWAN devices and Amazon Sidewalk enabled devices, as well as other devices that have been provisioned with AWS IoT devices that have been provisioned with AWS IoT. For general IoT devices, if the devices support location estimation using GNSS, when the GNSS scan information is received from the device, the transceivers resolve the location information. For LoRaWAN devices, the devices must have the LoRa Edge chipset. When an uplink message is received from the device, the GNSS scan data is sent to AWS IoT for LoRaWAN or AWS IoT for Amazon Sidewalk, and the location is estimated based on the scan results from the transceivers. ### GNSS solver payload example The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives the GNSS scan information containing the payload in the measurement data, it uses the transceivers and any additional assistance information included to search for signals and resolve the location information. To retrieve the information, either provide the JSON payload using this format, or specify values for the [Gnss](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-Gnss) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. **Note** Before AWS IoT Core Device Location can resolve the device location, you must remove the destination byte from the payload. ``` { "Timestamp": 1664313161, // optional "Gnss": { "AssistAltitude": number, // optional "AssistPosition": [ number ], // optional "CaptureTime": number, // optional "CaptureTimeAccuracy": number, // optional "Payload": "string", // required "Use2DSolver": boolean // optional } } ``` ## BLE solver for Amazon Sidewalk enabled devices **Note** For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you. Amazon Sidewalk end devices connecting over AWS IoT Core for Amazon Sidewalk can resolve their location data using BLE, Wi-Fi, or GNSS uplink messages published by the Amazon Sidewalk end device. For more information, see the [AWS IoT Core for Amazon Sidewalk developer guide](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/sidewalk-getting-started.html).