Location Data

Location data is the location of the thing, which is typically the location of the device on which the application runs.

You can acquire location information using a wireless network adapter or GPS antenna on your device. For example, you might want to track the location of a device in a building or the location of a device in a moving vehicle.

You can specify the following location properties:

Location Property

Description

latitude and longitude (mandatory)

decimal floating point numbers conforming to the WGS84 specification

source

source of the location data; valid sources are WiFi, GPS, fixed, and unknown

accuracy and altitude accuracy

accuracy in meters of the source of the location properties

heading

direction of travel specified as degrees clockwise of true north (range 0 through 359), where north is 0 degrees, east is 90 degrees and west is 270 degrees

altitude

altitude in meters

speed

speed of travel in meters per second

tag

string value to specify additional information about the sample

The C agent validates the values of latitude, longitude, and heading properties.

On the Management Portal, location information appears on the thing details page under the Overview tab. Under the Map tab on the Things page, you can see the location of things that have provided location information. For details about location data in Device Cloud, see the following:

  • Device Cloud Management Portal User's Guide: Things: Viewing and Updating Location Information of a Thing
  • Device Cloud Management Portal User's Guide: Thing Definitions: Defining Location

The location information defined in the thing definition can specify fix types to ignore, which are based on the values of the source property specified using the iot_location_source_set API. Ensure that you specify only fixed, gps, wifi, and unknown in the thing definition.

An organization administrator can specify the data retention periods for location data on the Configuration page on the Management Portal, which you can access from the Administration page.

Table 1. Python API

Function

Description

location_publish

Publish location information to Device Cloud.
Table 2. C APIs

Function

Description

iot_location_accuracy_set

Specify the accuracy of the location sample in meters.

iot_location_allocate

Create a location sample, allocate the required memory, and specify an initial location.

Valid location values:

  • latitude: -90 through 90

  • longitude: -180 through 180

iot_location_altitude_set

Specify the altitude of the location in meters.

iot_location_altitude_accuracy_set

Specify the accuracy of the altitude in meters.

iot_location_free

Destroy a location sample and free the associated memory.

iot_location_heading_set

Specify the heading of the location in degrees.

Valid values are from 0 through 360.

iot_location_set

Update the latitude and longitude of the location.

Valid values:

  • latitude: -90 through 90

  • longitude: -180 through 180

iot_location_source_set

Specify the source of the location data.

iot_location_speed_set

Specify the speed of the location sample in meters per second.

iot_location_tag_set

Specify a descriptive value of the location.