# Accessing device location information

The Location Service API allows widgets to retrieve information about the physical location of a device and to perform calculations based on location information. You can use the Location Service to create widgets that provide location-based services (LBS). For example, you can create widgets that:

- Provide directions to a destination, for example the nearest restaurant

- Monitor the locations of snow-plowing vehicles

- Calculate distances between geographical locations

The Location Service relies on the GPS capabilities of the device to provide location information. If the device does not include or is not connected to a positioning system, the service cannot provide such information.

### Accessing the API and supported methods

To create a service object for the Location Service API, use `Service.Location` to identify the service provider and `ILocation` to identify the supported interface:

    var so = device.getServiceObject("Service.Location", "ILocation");

The `ILocation` interface provides the following methods:

- `GetLocation()`

  Use the `GetLocation()` method to retrieve the current location of the device.

- `Trace()`

  Use the `Trace()` method to retrieve periodic updates about the current location of the device.

- `Calculate()`

  Use the `Calculate()` method to perform mathematical calculations based on a source location and a target location.

- `CancelNotification()`

  Use the `CancelNotification()` method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Location Service API.

### Using the service in a widget

To access location information using the Location Service API:

1. Create a service object for the API using `device.getServiceObject()`.

2. Define the tasks you want to perform and choose the correct methods for them.

3. Optionally, define how you want the results filtered.

4. Define methods for processing the results.

5. Retrieve the location information using the methods defined in step 2. Use asynchronous methods together with `callback()`.

6. Process the results with the methods defined in step 4.

For the complete source of a sample widget that demonstrates how to use this service, see the full example.