> 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

Track device location in the background using the WebToNative JavaScript API. Enable continuous location updates for Android and iOS apps.

{% 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",
 offlineQueue: false
})

//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",
 offlineQueue: false
})

//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.

**offlineQueue** : Stores background location updates in a queue when the device is offline and automatically sends the queued updates once the network connection is restored. In this mode, request bodies are sent as an array of location update objects.

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

### 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>