Sending Location Data to Device Cloud in C

A client application can send geolocation data to Device Cloud using the location APIs to monitor the device location.

To transmit location data, you create and register a telemetry object, create a location data sample, and specify the location data sample as the telemetry value when you publish the telemetry.

You need a wireless network adapter or GPS antenna and the associated drivers that are compatible with your board. For more information about the supported boards and hardware, see the information for the supported operating systems.

If you use a wireless network for location data, you need software libraries on your device to access geolocation data from a service provider, such as Google. Depending on your service provider, you may need a commercial subscription.

You must have previously initialized your application (see Initializing Your C Application).

Before you run your application, the thing definition that corresponds to your application must be defined.

To send data to Device Cloud, the application must be connected to Device Cloud.

Allocate the memory for the location telemetry object.
For the handle parameter, specify the value returned from the iot_initialize function, which you called when you registered your application.

Specify the value returned from the iot_initialize function, which you called when you registered your application, for the handle parameter.

For the type parameter, specify IOT_TYPE_LOCATION.

The value you specify for the name parameter is only used internally by the agent to ensure that the telemetry object is unique. Specify any valid string.
```
iot_telemetry_t* location_telemetry;
location_telemetry = iot_telemetry_allocate(agentLib, "location", IOT_TYPE_LOCATION);
```
Register the location telemetry object with the agent.
For the txn parameter, specify NULL and for the max_time_out parameter, specify zero.
```
result = iot_telemetry_register(location_telemetry, NULL, 0);
```
Allocate the memory for the location data sample and specify the mandatory location information.
Retrieve the location data from your geolocation service provider, GPS antenna, or use fixed values.

Specify latitude and longitude as decimal values.
```
struct iot_location_t* location_data;
iot_float64_t latitude;
iot_float64_t longitude;

/* obtain location information - not shown */

location_data = iot_location_allocate( latitude, longitude );
```
(Optional) Specify the source of the location data.
For the sample parameter, specify the value returned from the iot_location_allocate function.
```
result = iot_location_source_set( location_data, IOT_LOCATION_SOURCE_GPS );
```

(Optional) Specify optional location attributes as required, either with fixed values or values obtained from your service provider.

result = iot_location_accuracy_set( location_data, accuracy_value );
result = iot_location_altitude_set( location_data, altitude_value );
result = iot_location_tag_set( location_data, "Kitchen" );

Send the location data sample to Device Cloud.
For the txn parameter, specify NULL, and for the max_time_out parameter, specify zero.

For the data parameter, specify the location data sample.
```
result = iot_telemetry_publish( location_telemetry, NULL, 0, IOT_TYPE_LOCATION, 
                                location_data );
```
When your application runs, the application transmits the location data to Device Cloud. If the location source is not in the Fix types to ignore list in the thing definition, the thing details page shows the new location and the device position on the map changes.
To update the location of the device, call the iot_location_set with new latitude and longitude values.
```
result = iot_location_set( location_data, -80.00, 100.9);
result = iot_telemetry_publish( location_telemetry, NULL, 0, IOT_TYPE_LOCATION, 
                                location_data );
```
The application transmits the new location data to Device Cloud.

Examples

The iot-app-simple-location sample application provided with the agent shows example code for sending location data to Device Cloud with all attributes specified.

If you do not need the location data sample and the telemetry object after you send the location data, call the iot_location_free, iot_telemetry_deregister, and iot_telemetry_free functions to free the associated memory.