> For the complete documentation index, see [llms.txt](https://docs.webtonative.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webtonative.com/javascript-apis/background-location.md).

# Background Location API

{% hint style="info" %}

<pre data-overflow="wrap"><code>You'll need to import the javascript file in your website before starting from this <a data-footnote-ref href="#user-content-fn-1">link</a>.
</code></pre>

{% endhint %}

**To retrieve device location even when app is in background state**

{% tabs %}
{% tab title="Plain JS" %}

<pre><code>//to start recieving location updates
<strong>window.WTN.backgroundLocation.start({
</strong> apiUrl,
 timeout,
 data,
 backgroundIndicator : false,
 pauseAutomatically : true,
 distanceFilter : 0.0,
 desiredAccuracy : "best",
 activityType : "other",
})

//to stop recieving location updates
<strong>window.WTN.backgroundLocation.stop()
</strong> 
 
</code></pre>

{% endtab %}

{% tab title="ES 6+" %}

```
import { start, stop } from "webtonative/BackgroundLocation"

//to start recieving location updates
start({
 apiUrl,
 timeout,
 data,
 backgroundIndicator : false,
 pauseAutomatically : true,
 distanceFilter : 0.0,
 desiredAccuracy : "best",
 activityType : "other",
})

//to stop recieving location updates
stop()
```

{% endtab %}
{% endtabs %}

### Call the method with the following data

**apiUrl** (Mandatory): The API endpoint that will be called using the POST method to send location data.

* **Value Type**: **String**
* **Example**: `https://backgrounlocation.free.beeceptor.com/`

**timeout**: The time interval between API calls, measured in milliseconds.

* **Value Type**: Number
* **Example**: `1000 milliseconds = 1 second`

**data** (Optional)**:** Extra data to send along with the location update. Useful for identifying users or adding metadata. Can also use query parameters.

* **Value Type**: JSON object
* **Example**: `{ "keyName": "value" }`

**backgroundIndicator** (Optional, iOS Only)**:** Modifies the iOS status bar to indicate that the app is using location services when in the background.

* **Value Type**: Boolean
* **Default Value**: `false`

**pauseAutomatically** (Optional, iOS Only): When set to "true," The location manager pauses updates (and powers down hardware) when location data is unlikely to change, improving battery life.

* **Value Type**: Boolean
* **Default Value**: `true`

**distanceFilter**: The minimum horizontal distance (in meters) a device must move before an update is generated.

* **Value Type**: Double
* **Default Value**: `0.0` meters
* **Example**: If set to `10.0`, data is logged only after the device moves 10 meters.

**desiredAccuracy** (Optional, iOS Only)**:** The desired accuracy of location data. Higher accuracy increases battery consumption.

* **Value Type**: String
* **Default Value**: `best`
* **Possible Values**:
  * `best` : The best accuracy possible (default).
  * `bestForNavigation`: Highest accuracy using additional sensor data for navigation apps.
  * `tenMeters`: Accurate to within 10 meters.
  * `hundredMeters`: Accurate to within 100 meters.
  * `kilometer`: Accurate to the nearest kilometer.
  * `threekilometers`: Accurate to the nearest 3 kilometers.

**activityType** (Optional, iOS Only): The user activity associated with location updates.

* **Value Type**: String
* **Default Value**: `other`
* **Possible Values**:
  * `other`: Unknown activity (default).
  * `automotiveNavigation`: Vehicular navigation for automobiles.
  * `otherNavigation`: Non-automobile vehicular navigation.
  * `fitness`: Tracking fitness activities (e.g., walking, running, cycling).
  * `airborne`: Tracking airborne activities.

### Notes

* **Foreground Behavior**: Location updates are sent to the `apiUrl`.
* **Background Behavior**: Location updates are sent only to `apiUrl` when the app is in the background.

### Location Object

The location data sent to your API or callback function includes the following fields:

* `latitude`: Latitude in degrees.
* `longitude`: Longitude in degrees.
* `altitude`: Altitude in meters.
* `timestamp`: Time of the location update (milliseconds since Jan 1, 1970).
* `data`: The extra data provided in the `start` method.
* `floor` (iOS Only): The logical floor of the building.
* `deviceID`: Device identifier.
* `playerId`: OneSignal Player ID (if OneSignal is enabled).
* `speed`: Instantaneous speed of the device (meters per second).
* `direction` (iOS Only): Device pointing direction (e.g., N, NE, E, SE, S, SW, W, NW, or none).
* `horizontalAccuracy` (iOS Only): Radius of uncertainty for the location (in meters).
* `verticalAccuracy`: Validity and estimated uncertainty of altitude values (in meters).

***

[^1]: <https://docs.webtonative.com/javascript-apis/getting-started>