# Background Location

{% 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.webtonative.com/javascript-apis/background-location.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.