# PhoneGap Documentation

# Compass

> Obtains the direction that the device is pointing.

## Methods

- compass.getCurrentHeading
- compass.watchHeading
- compass.clearWatch
- compass.watchHeadingFilter (obsolete)
- compass.clearWatchFilter (obsolete)

## Arguments

- compassSuccess
- compassError
- compassOptions
- compassHeading

## Permissions

### Android

#### app/res/xml/config.xml

    <plugin name="Compass" value="org.apache.cordova.CompassListener" />

### BlackBerry WebWorks

    No permissions are required.

### iOS

#### config.xml

    <plugin name="Compass" value="CDVLocation" />

### Windows Phone

#### Properties/WPAppManifest.xml

    <Capabilities>
        <Capability Name="ID_CAP_SENSORS" />
    </Capabilities>

Reference: Application Manifest for Windows Phone

### Tizen

    No permissions are required.

# compass.getCurrentHeading

Get the current compass heading.

    navigator.compass.getCurrentHeading(compassSuccess, compassError, compassOptions);

## Description

The compass is a sensor that detects the direction or heading that the device is pointed, typically from the top of the device. It measures the heading in degrees from 0 to 359.99, where 0 is north.

The compass heading information is returned via a `CompassHeading` object using the `compassSuccess` callback function.

## Supported Platforms

- Android
- iOS
- Tizen
- Windows Phone 7 and 8 ( if available in hardware )
- Windows 8

## Quick Example

    function onSuccess(heading) {
        alert('Heading: ' + heading.magneticHeading);
    };

    function onError(error) {
        alert('CompassError: ' + error.code);
    };

    navigator.compass.getCurrentHeading(onSuccess, onError);

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>Compass Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            navigator.compass.getCurrentHeading(onSuccess, onError);
        }

        // onSuccess: Get the current heading
        //
        function onSuccess(heading) {
            alert('Heading: ' + heading.magneticHeading);
        }

        // onError: Failed to get the heading
        //
        function onError(compassError) {
            alert('Compass Error: ' + compassError.code);
        }

        </script>
      </head>
      <body>
        <h1>Example</h1>
        <p>getCurrentHeading</p>
      </body>
    </html>

# compass.watchHeading

At a regular interval, get the compass heading in degrees.

    var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);

## Description

The compass is a sensor that detects the direction or heading that the device is pointed. It measures the heading in degrees from 0 to 359.99.

The `compass.watchHeading` gets the device's current heading at a regular interval. Each time the heading is retrieved, the `headingSuccess` callback function is executed. Specify the interval in milliseconds via the `frequency` parameter in the `compassOptions` object.

The returned watch ID references the compass watch interval. The watch ID can be used with `compass.clearWatch` to stop watching the compass.

## Supported Platforms

- Android
- iOS
- Tizen
- Windows Phone 7 and 8 (if available in hardware)
- Windows 8

## Quick Example

    function onSuccess(heading) {
        var element = document.getElementById('heading');
        element.innerHTML = 'Heading: ' + heading.magneticHeading;
    };

    function onError(compassError) {
        alert('Compass error: ' + compassError.code);
    };

    var options = {
        frequency: 3000
    }; // Update every 3 seconds

    var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>Compass Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // The watch id references the current `watchHeading`
        var watchID = null;

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            startWatch();
        }

        // Start watching the compass
        //
        function startWatch() {

            // Update compass every 3 seconds
            var options = { frequency: 3000 };

            watchID = navigator.compass.watchHeading(onSuccess, onError, options);
        }

        // Stop watching the compass
        //
        function stopWatch() {
            if (watchID) {
                navigator.compass.clearWatch(watchID);
                watchID = null;
            }
        }

        // onSuccess: Get the current heading
        //
        function onSuccess(heading) {
            var element = document.getElementById('heading');
            element.innerHTML = 'Heading: ' + heading.magneticHeading;
        }

        // onError: Failed to get the heading
        //
        function onError(compassError) {
            alert('Compass error: ' + compassError.code);
        }

        </script>
      </head>
      <body>
        <div id="heading">Waiting for heading...</div>
        <button onclick="startWatch();">Start Watching</button>
        <button onclick="stopWatch();">Stop Watching</button>
      </body>
    </html>

## iOS Quirks

In iOS `compass.watchHeading` can also get the device's current heading when it changes by a specified number of degrees. Each time the heading changes by the specified number of degrees or more, the `headingSuccess` callback function executes. Specify the degrees of change via the `filter` parameter in the `compassOptions` object. Clear the watch as usual by passing the returned watch ID to `compass.clearWatch`. This functionality replaces the previously separate, iOS-only `watchHeadingFilter` and `clearWatchFilter` functions, which were removed in version 1.6.

Only one `watchHeading` can be in effect at one time in iOS. If a `watchHeading` uses a filter, calling `getCurrentHeading` or `watchHeading` uses the existing filter value to specify heading changes. Watching heading changes with a filter is more efficient than with time intervals.

# compass.clearWatch

Stop watching the compass referenced by the watch ID parameter.

    navigator.compass.clearWatch(watchID);

- watchID: The ID returned by `compass.watchHeading`.

## Supported Platforms

- Android
- iOS
- Tizen
- Windows Phone 7 and 8 ( if available in hardware )
- Windows 8

## Quick Example

    var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

    // ... later on ...

    navigator.compass.clearWatch(watchID);

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>Compass Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // The watch id references the current `watchHeading`
        var watchID = null;

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            startWatch();
        }

        // Start watching the compass
        //
        function startWatch() {

            // Update compass every 3 seconds
            var options = { frequency: 3000 };

            watchID = navigator.compass.watchHeading(onSuccess, onError, options);
        }

        // Stop watching the compass
        //
        function stopWatch() {
            if (watchID) {
                navigator.compass.clearWatch(watchID);
                watchID = null;
            }
        }

        // onSuccess: Get the current heading
        //
        function onSuccess(heading) {
            var element = document.getElementById('heading');
            element.innerHTML = 'Heading: ' + heading.magneticHeading;
        }

        // onError: Failed to get the heading
        //
        function onError(compassError) {
            alert('Compass error: ' + compassError.code);
        }

        </script>
      </head>
      <body>
        <div id="heading">Waiting for heading...</div>
        <button onclick="startWatch();">Start Watching</button>
        <button onclick="stopWatch();">Stop Watching</button>
      </body>
    </html>

# compass.watchHeadingFilter

No longer supported as of 1.6, see `compass.watchHeading` for equivalent functionality.

# compass.clearWatchFilter

No longer supported as of 1.6. See `compass.clearWatch`.

# compassSuccess

onSuccess callback function that provides the compass heading information via a `compassHeading` object.

    function(heading) {
        // Do something
    }

## Parameters

- heading: The heading information. (compassHeading)

## Example

    function onSuccess(heading) {
        alert('Heading: ' + heading.magneticHeading);
    };

# compassError

onError callback function for compass functions.

## Example

    function(CompassError) {
        // Handle the error
    }

# compassOptions

An optional parameter to customize the retrieval of the compass.

## Options

- frequency: How often to retrieve the compass heading in milliseconds. (Number) (Default: 100)
- filter: The change in degrees required to initiate a watchHeading success callback. (Number)

Android Quirks

- `filter` is not supported.

## Tizen Quirks

- `filter` is not supported.

## Windows Phone 7 and 8 Quirks

- `filter` is not supported.

# compassHeading

A `CompassHeading` object is returned to the `compassSuccess` callback function.

## Properties

- magneticHeading: The heading in degrees from 0 - 359.99 at a single moment in time. (Number)
- trueHeading: The heading relative to the geographic North Pole in degrees 0 - 359.99 at a single moment in time. A negative value indicates that the true heading cannot be determined. (Number)
- headingAccuracy: The deviation in degrees between the reported heading and the true heading. (Number)
- timestamp: The time at which this heading was determined. (milliseconds)

## Description

The `CompassHeading` object is returned to the `compassSuccess` callback function.

## Android Quirks

- `trueHeading` is not supported, but reports the same value as `magneticHeading`
- `headingAccuracy` is always 0 because there is no difference between the `magneticHeading` and `trueHeading`.

## iOS Quirks

- `trueHeading` is only returned when location services are enabled via `navigator.geolocation.watchLocation()`
- For iOS 4 devices and above, heading factors in the device's current orientation, not in reference to its absolute position, for apps that supports that orientation.

# CompassError

A `CompassError` object is returned to the `compassError` callback function when an error occurs.

## Properties

- code: One of the predefined error codes listed below.

## Constants

- `CompassError.COMPASS_INTERNAL_ERR`
- `CompassError.COMPASS_NOT_SUPPORTED`

## Description

When an error occurs, the `CompassError` object is passed as a parameter to a `compassError` callback function.