### Quick Start with JavaScript SDK

Source: https://www.localsdk.com/docs/sdks/javascript

Initialize the SDK, start location tracking, and listen for location updates.

```javascript
import LocalSDK from '@localsdk/js';

const sdk = new LocalSDK({
  apiKey: 'your_api_key',
  trackingMode: 'adaptive',
});

sdk.startTracking();

sdk.on('location', (update) => {
  console.log(`${update.latitude}, ${update.longitude}`);
});
```

--------------------------------

### Install JavaScript SDK

Source: https://www.localsdk.com/docs/sdks/javascript

Install the LocalSDK JavaScript package using npm.

```bash
npm install @localsdk/js
```

--------------------------------

### Initialize and Start Tracking with LocalSDK

Source: https://www.localsdk.com/docs/sdks/android

Initialize the SDK with your API key and start adaptive tracking. Listen for location updates.

```kotlin
import com.localsdk.LocalSDK
import com.localsdk.TrackingMode

val sdk = LocalSDK.init(context, "your_api_key")

sdk.startTracking(TrackingMode.ADAPTIVE)

sdk.onLocation { update ->
    Log.d("Location", "${update.latitude}, ${update.longitude}")
}
```

--------------------------------

### API Authentication Example

Source: https://www.localsdk.com/docs/api-reference/authentication

This example shows how to authenticate with the LocalSDK API by including your API key in the Authorization header.

```APIDOC
## Authenticate with the LocalSDK API

### Description
Authenticate with the LocalSDK API using Bearer tokens. Include your API key in the `Authorization` header of every request.

### Method
`GET` (example, actual method depends on the endpoint)

### Endpoint
`https://api.localsdk.com/api/v1/locations/current`

### Request Headers
- `Authorization`: `Bearer YOUR_API_KEY`

### Request Example
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.localsdk.com/api/v1/locations/current
```
```

--------------------------------

### Install Expo

Source: https://www.localsdk.com/docs/sdks/react-native

Use this command to install the React Native SDK for Expo projects.

```bash
npx expo install @localsdk/react-native
```

--------------------------------

### Install Bare React Native

Source: https://www.localsdk.com/docs/sdks/react-native

Use these commands to install the React Native SDK for bare React Native projects.

```bash
npm install @localsdk/react-native
npx pod-install
```

--------------------------------

### Install LocalSDK for React Native

Source: https://www.localsdk.com/docs/installation

Install the React Native SDK using npx or npm. For bare React Native projects, also run `npx pod-install`.

```bash
npx expo install @localsdk/react-native
```

```bash
npm install @localsdk/react-native
npx pod-install
```

--------------------------------

### Initialize and Start LocalSDK

Source: https://www.localsdk.com/docs/sdks/ios

Initialize the SDK with your API key and begin location tracking in adaptive mode. A callback is provided to print location updates.

```swift
import LocalSDK

let sdk = LocalSDK(apiKey: "your_api_key")

sdk.startTracking(mode: .adaptive)

sdk.onLocation { update in
    print("Location: \(update.latitude), \(update.longitude)")
}
```

--------------------------------

### Install LocalSDK with CocoaPods

Source: https://www.localsdk.com/docs/sdks/ios

Add the LocalSDK CocoaPods dependency to your Podfile.

```ruby
pod 'LocalSDK', '~> 2.0'
```

--------------------------------

### Start Background Tracking with Foreground Service

Source: https://www.localsdk.com/docs/sdks/android

Enable background tracking using a foreground service, providing a notification configuration for user awareness.

```kotlin
sdk.startTracking(
    mode = TrackingMode.ADAPTIVE,
    foregroundService = true,
    notificationConfig = NotificationConfig(
        title = "Tracking active",
        icon = R.drawable.ic_location
    )
)
```

--------------------------------

### Install LocalSDK with Swift Package Manager

Source: https://www.localsdk.com/docs/sdks/ios

Add the LocalSDK Swift Package Manager dependency to your Xcode project.

```swift
dependencies: [
    .package(url: "https://github.com/localsdk/localsdk-ios.git", from: "2.0.0")
]
```

--------------------------------

### Get Current Location by User

Source: https://www.localsdk.com/docs/api-reference/user-location

Obtain the latest positions for all devices owned by a specific user.

```APIDOC
## GET /api/v1/users/{user_id}/locations/current

### Description
Obtain the latest positions for all devices owned by a specific user.

### Method
GET

### Endpoint
`/api/v1/users/{user_id}/locations/current`

### Authorization
`BearerAuth`
Authorization: Bearer <token>
API key obtained from the LocalSDK admin panel. Pass as: `Authorization: Bearer <api_key>`
In: `header`

### Path Parameters
- **user_id** (string) - Required - User identifier. Cannot be "ANONYMOUS".

### Query Parameters
- **max_age** (integer) - Optional - Maximum age of location in seconds. Range `0 <= value`.
- **accuracy** (integer) - Optional - Minimum accuracy requirement in meters (locations with horizontal_accuracy greater than this are excluded). Range `0 <= value`.
- **limit** (integer) - Optional - Number of results to return. Default `100`. Range `1 <= value <= 1000`.
- **timezone** (string) - Optional - Timezone for timestamp conversion. Accepts IANA names, UTC offsets, or abbreviations.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **user_id** (string) - The ID of the user.
- **device_count** (integer) - The number of devices found for the user.
- **locations** (array) - An array of location objects for the user's devices.
  - **device_id** (string) - The ID of the device.
  - **app_id** (string) - The ID of the application.
  - **timestamp** (integer) - The timestamp of the location in milliseconds.
  - **latitude** (number) - The latitude coordinate.
  - **longitude** (number) - The longitude coordinate.
  - **horizontal_accuracy** (number) - The horizontal accuracy of the location in meters.
  - **vertical_accuracy** (number) - The vertical accuracy of the location in meters.
  - **altitude** (number) - The altitude of the location in meters.
  - **speed** (number) - The speed of the device in meters per second.
  - **bearing** (number) - The bearing of the device in degrees.
  - **type** (string) - The type of location (e.g., "STATIONARY").
  - **battery_level** (integer) - The battery level of the device (0-100).
  - **battery_status** (string) - The battery status (e.g., "Not Charging").
  - **network_status** (boolean) - Indicates if the device has network connectivity.
  - **location_permission** (boolean) - Indicates if location permission is granted.
  - **is_mock** (boolean) - Indicates if the location is mock.
  - **tracking_mode** (string) - The tracking mode of the device (e.g., "PRECISE").
  - **tz_offset** (string) - The timezone offset.
  - **user_id** (string) - The ID of the user.

#### Response Example (200)
```json
{
  "success": true,
  "user_id": "user_123",
  "device_count": 2,
  "locations": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "app_id": "app_a1b2c3d4e5f6",
      "timestamp": 1709564400000,
      "latitude": 33.4484,
      "longitude": -112.074,
      "horizontal_accuracy": 6.5,
      "vertical_accuracy": 3.2,
      "altitude": 331.2,
      "speed": 0,
      "bearing": 0,
      "type": "STATIONARY",
      "battery_level": 78,
      "battery_status": "Not Charging",
      "network_status": true,
      "location_permission": true,
      "is_mock": false,
      "tracking_mode": "PRECISE",
      "tz_offset": "-7",
      "user_id": "user_123"
    },
    {
      "device_id": "82g6504d51fb36943h07g846",
      "app_id": "app_a1b2c3d4e5f6",
      "timestamp": 1709563200000,
      "latitude": 33.4255,
      "longitude": -111.94,
      "horizontal_accuracy": 12,
      "vertical_accuracy": 5.1,
      "altitude": 362,
      "speed": 0.3,
      "bearing": 215,
      "type": "STATIONARY",
      "battery_level": 55,
      "battery_status": "Not Charging",
      "network_status": true,
      "location_permission": true,
      "is_mock": false,
      "tracking_mode": "BALANCED",
      "tz_offset": "-7",
      "user_id": "user_123"
    }
  ]
}
```

#### Error Response (400)
```json
{
  "error": "Invalid user_id",
  "message": "user_id is required and cannot be ANONYMOUS"
}
```

#### Error Response (401)
```json
{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": "AUTH_001",
  "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
}
```
```

--------------------------------

### Start Location Tracking and Listen for Updates

Source: https://www.localsdk.com/docs/quickstart

Begin tracking user locations and set up a listener to receive location updates. The update object contains latitude and longitude.

```javascript
// Start location tracking
 sdk.startTracking();

// Listen for location updates
 sdk.on('location', (update) => {
  console.log(`Lat: ${update.latitude}, Lng: ${update.longitude}`);
 });
```

--------------------------------

### Search Nearby Devices (cURL)

Source: https://www.localsdk.com/docs/api-reference/devices

Example of how to search for devices within a radius of a geographic point using cURL. Ensure to replace the placeholder with your actual API key.

```bash
curl -X GET "https://api.localsdk.com/api/v1/devices/nearby?latitude=-90&longitude=-180" \
  -H "Authorization: Bearer "
```

--------------------------------

### Quick Start with useLocation Hook

Source: https://www.localsdk.com/docs/sdks/react-native

Initialize the SDK and use the useLocation hook to track user location in your React Native application. Ensure initialization happens once at app startup.

```javascript
import { LocalSDK, useLocation } from '@localsdk/react-native';

// Initialize once at app startup
LocalSDK.init({ apiKey: 'your_api_key' });

function TrackingScreen() {
  const { location, isTracking } = useLocation({
    mode: 'adaptive',
    interval: 5000,
  });

  return (
    <View>
      <Text>Tracking: {isTracking ? 'Active' : 'Inactive'}</Text>
      {location && (
        <Text>
          {location.latitude}, {location.longitude}
        </Text>
      )}
    </View>
  );
}
```

--------------------------------

### Add LocalSDK to Flutter Project

Source: https://www.localsdk.com/docs/installation

Add the LocalSDK as a dependency in your Flutter project's pubspec.yaml file and run `flutter pub get`.

```yaml
dependencies:
  localsdk: ^2.0.0
```

--------------------------------

### Get Location History by User

Source: https://www.localsdk.com/docs/api-reference/user-location

Access historical position data for all devices owned by a specific user.

```APIDOC
## GET /api/v1/users/{user_id}/locations/history

### Description
Access historical position data for all devices owned by a specific user. The `distance_travelled` parameter only works for single-day queries.

### Method
GET

### Endpoint
`/api/v1/users/{user_id}/locations/history`

### Authorization
`BearerAuth`
Authorization: Bearer <token>
API key obtained from the LocalSDK admin panel. Pass as: `Authorization: Bearer <api_key>`
In: `header`

### Path Parameters
- **user_id** (string) - Required - User identifier. Cannot be "ANONYMOUS".

### Query Parameters
- **start_date** (string) - Optional - Start date in `YYYY-MM-DD` format. Defaults to today if omitted.
- **end_date** (string) - Optional - End date in `YYYY-MM-DD` format. Defaults to today if omitted.
- **limit** (integer) - Optional - Number of results per page. Default `100`. Range `1 <= value <= 1000`.
- **offset** (integer) - Optional - Number of results to skip for pagination. Default `0`. Range `0 <= value`.
- **timezone** (string) - Optional - Timezone for timestamp conversion. Accepts IANA names, UTC offsets, or abbreviations.
- **distance_travelled** (string) - Optional - Set to `true` to calculate total distance travelled. Only supported on single-day queries (start_date must equal end_date). Uses Haversine formula. Default `"false"`. Value in `"true" | "false"`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **user_id** (string) - The ID of the user.
- **locations** (array) - An array of historical location objects for the user's devices.
  - **device_id** (string) - The ID of the device.
  - **app_id** (string) - The ID of the application.
  - **timestamp** (integer) - The timestamp of the location in milliseconds.
  - **latitude** (number) - The latitude coordinate.
  - **longitude** (number) - The longitude coordinate.
  - **horizontal_accuracy** (number) - The horizontal accuracy of the location in meters.
  - **vertical_accuracy** (number) - The vertical accuracy of the location in meters.
  - **altitude** (number) - The altitude of the location in meters.
  - **speed** (number) - The speed of the device in meters per second.
  - **bearing** (number) - The bearing of the device in degrees.
  - **type** (string) - The type of location (e.g., "STATIONARY").
  - **battery_level** (integer) - The battery level of the device (0-100).
  - **battery_status** (string) - The battery status (e.g., "Not Charging").
  - **network_status** (boolean) - Indicates if the device has network connectivity.
  - **location_permission** (boolean) - Indicates if location permission is granted.
  - **is_mock** (boolean) - Indicates if the location is mock.
  - **tracking_mode** (string) - The tracking mode of the device (e.g., "PRECISE").
  - **tz_offset** (string) - The timezone offset.
  - **user_id** (string) - The ID of the user.
  - **distance_travelled** (number) - The total distance travelled in meters (only available if `distance_travelled` query parameter is set to `true` and it's a single-day query).
```

--------------------------------

### cURL Request for Location History

Source: https://www.localsdk.com/docs/api-reference/location-history

Example cURL command to fetch location history data. Ensure to replace the placeholder with your actual Bearer token.

```curl
curl -X GET "https://api.localsdk.com/api/v1/locations/history?start_date=2026-03-01&end_date=2026-03-03&timezone=America%2FPhoenix" \
  -H "Authorization: Bearer "
```

--------------------------------

### Successful Response for Single Device Location

Source: https://www.localsdk.com/docs/api-reference/current-location

This is an example of a successful response when retrieving the current location of a single device. It includes detailed location information such as latitude, longitude, timestamp, and accuracy.

```JSON
{
  "success": true,
  "device_id": "68e4382b39d914721f85e624",
  "location": {
    "device_id": "68e4382b39d914721f85e624",
    "app_id": "app_a1b2c3d4e5f6",
    "timestamp": 1709564400000,
    "latitude": 33.4484,
    "longitude": -112.074,
    "horizontal_accuracy": 6.5,
    "vertical_accuracy": 3.2,
    "altitude": 331.2,
    "speed": 0,
    "bearing": 0,
    "type": "STATIONARY",
    "battery_level": 78,
    "battery_status": "Not Charging",
    "network_status": true,
    "location_permission": true,
    "is_mock": false,
    "tracking_mode": "PRECISE",
    "tz_offset": "-7",
    "user_id": "user_123",
    "id": "loc_9f8e7d6c5b4a"
  }
}
```

--------------------------------

### Successful Response for All Devices Locations

Source: https://www.localsdk.com/docs/api-reference/current-location

An example of a successful response when retrieving current locations for all devices. The response includes a list of location objects, each containing device details and location data, along with pagination information.

```JSON
{
  "success": true,
  "app_id": "app_a1b2c3d4e5f6",
  "locations": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "app_id": "app_a1b2c3d4e5f6",
      "timestamp": 1709564400000,
      "latitude": 33.4484,
      "longitude": -112.074,
      "horizontal_accuracy": 6.5,
      "vertical_accuracy": 3.2,
      "altitude": 331.2,
      "speed": 0,
      "bearing": 0,
      "type": "STATIONARY",
      "battery_level": 78,
      "battery_status": "Not Charging",
      "network_status": true,
      "location_permission": true,
      "is_mock": false,
      "tracking_mode": "PRECISE",
      "tz_offset": "-7",
      "user_id": "user_123"
    },
    {
      "device_id": "71f5493c40ea25832g96f735",
      "app_id": "app_a1b2c3d4e5f6",
      "timestamp": 1709564380000,
      "latitude": 40.7128,
      "longitude": -74.006,
      "horizontal_accuracy": 4.1,
      "vertical_accuracy": 2.8,
      "altitude": 10.8,
      "speed": 12.5,
      "bearing": 87,
      "type": "MOVING",
      "battery_level": 42,
      "battery_status": "Charging",
      "network_status": true,
      "location_permission": true,
      "is_mock": false,
      "tracking_mode": "PRECISE",
      "tz_offset": "-5",
      "user_id": "user_456"
    }
  ],
  "pagination": {
    "count": 2,
    "has_more": false,
    "total_count": 2,
    "offset": 0,
    "limit": 100
  }
}
```

--------------------------------

### Nearby Devices API Response (Invalid Latitude)

Source: https://www.localsdk.com/docs/api-reference/devices

An example of an error response when the provided latitude is outside the valid range of -90 to 90.

```json
{
  "success": false,
  "message": "Invalid latitude. Must be between -90 and 90"
}
```

--------------------------------

### Authenticate API Request with Bearer Token

Source: https://www.localsdk.com/docs/api-reference/authentication

Include your API key in the `Authorization` header of every request to authenticate with the LocalSDK API. This example shows a `curl` command for making an authenticated request.

```curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.localsdk.com/api/v1/locations/current
```

--------------------------------

### Error Response: Invalid Timezone

Source: https://www.localsdk.com/docs/api-reference/current-location

An example of an error response when an invalid timezone is provided. The response indicates the failure and specifies the invalid timezone value.

```JSON
{
  "success": false,
  "message": "Invalid timezone: Invalid/Zone"
}
```

--------------------------------

### Get Current Locations for All Devices

Source: https://www.localsdk.com/docs/api-reference/current-location

Fetch the latest positions for all devices associated with your application. You can use query parameters like `limit`, `offset`, `timestamp_after`, `timestamp_before`, and `timezone` to filter and paginate results.

```cURL
curl -X GET "https://api.localsdk.com/api/v1/locations/current?timezone=America%2FPhoenix" \
  -H "Authorization: Bearer "
```

--------------------------------

### Successful Location History Response

Source: https://www.localsdk.com/docs/api-reference/location-history

This is an example of a successful response when retrieving location history. It includes device information, a list of locations with detailed data points, and pagination information. The `query_info` field provides details about the data scanned and query execution time.

```json
{
  "success": true,
  "device_id": "68e4382b39d914721f85e624",
  "locations": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "timestamp": 1709564400000,
      "latitude": 33.4484,
      "longitude": -112.074,
      "horizontal_accuracy": 6.5,
      "vertical_accuracy": 3.2,
      "altitude": 331.2,
      "speed": 0,
      "bearing": 0,
      "type": "STATIONARY",
      "battery_level": 78,
      "battery_status": "Not Charging",
      "is_mock": false,
      "network_status": true,
      "tracking_mode": "PRECISE",
      "location_permission": true,
      "appId": "app_a1b2c3d4e5f6",
      "user_id": "user_123",
      "tz_offset": "-7",
      "id": "loc_9f8e7d6c5b4a",
      "brand": "Google",
      "model": "Pixel 8",
      "os": "android",
      "os_version": "14",
      "sdk_version": "2.1.0",
      "app_version_name": "1.5.0",
      "app_version_code": "150"
    },
    {
      "device_id": "68e4382b39d914721f85e624",
      "timestamp": 1709553600000,
      "latitude": 33.451,
      "longitude": -112.0685,
      "horizontal_accuracy": 5,
      "vertical_accuracy": 2.9,
      "altitude": 329.8,
      "speed": 8.9,
      "bearing": 45,
      "type": "MOVING",
      "battery_level": 82,
      "battery_status": "Not Charging",
      "is_mock": false,
      "network_status": true,
      "tracking_mode": "PRECISE",
      "location_permission": true,
      "appId": "app_a1b2c3d4e5f6",
      "user_id": "user_123",
      "tz_offset": "-7",
      "id": "loc_a1b2c3d4e5f6",
      "brand": "Google",
      "model": "Pixel 8",
      "os": "android",
      "os_version": "14"
    }
  ],
  "pagination": {
    "count": 2,
    "has_more": true
  },
  "query_info": {
    "time_range": {
      "start": "2026-03-03T00:00:00.000Z",
      "end": "2026-03-03T23:59:59.999Z"
    },
    "data_scanned_mb": 1.24,
    "query_time_ms": 230
  }
}
```

--------------------------------

### Initialize LocalSDK with API Key

Source: https://www.localsdk.com/docs/quickstart

Initialize the LocalSDK client with your API key and configure tracking options like tracking mode and update interval.

```javascript
import LocalSDK from '@localsdk/js';

const sdk = new LocalSDK({
  apiKey: 'your_api_key',
  trackingMode: 'adaptive',
  updateInterval: 5000,
});
```

--------------------------------

### Get User Location History

Source: https://www.localsdk.com/docs/api-reference/user-location

Retrieves historical location data for a specific user within a given date range.

```APIDOC
## GET /api/v1/users/{user_id}/locations/history

### Description
Retrieves historical location data for a specific user within a given date range.

### Method
GET

### Endpoint
/api/v1/users/{user_id}/locations/history

### Parameters
#### Query Parameters
- **start_date** (string) - Required - The start date for the location history query (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the location history query (YYYY-MM-DD).
- **timezone** (string) - Optional - The timezone to use for the query (e.g., America/Phoenix).

### Request Example
```json
{
  "example": "curl -X GET \"https://api.localsdk.com/api/v1/users/user_123/locations/history?start_date=2026-03-01&end_date=2026-03-03&timezone=America%2FPhoenix\" \
  -H \"Authorization: Bearer <api_key>\""
}
```

### Response
#### Success Response (200)
- **user_id** (string) - The ID of the user.
- **locations** (array) - An array of location objects.
  - **device_id** (string) - The ID of the device.
  - **timestamp** (integer) - The timestamp of the location in milliseconds.
  - **latitude** (number) - The latitude coordinate.
  - **longitude** (number) - The longitude coordinate.
  - **horizontal_accuracy** (number) - The horizontal accuracy of the location.
  - **vertical_accuracy** (number) - The vertical accuracy of the location.
  - **altitude** (number) - The altitude of the location.
  - **speed** (number) - The speed at the time of the location.
  - **bearing** (number) - The bearing at the time of the location.
  - **type** (string) - The type of location (e.g., STATIONARY).
  - **battery_level** (integer) - The battery level of the device.
  - **battery_status** (string) - The battery status of the device.
  - **is_mock** (boolean) - Indicates if the location is mocked.
  - **network_status** (boolean) - Indicates the network status.
  - **tracking_mode** (string) - The tracking mode used.
  - **location_permission** (boolean) - Indicates if location permission is granted.
  - **appId** (string) - The ID of the application.
  - **user_id** (string) - The ID of the user.
  - **tz_offset** (string) - The timezone offset.
  - **id** (string) - The ID of the location record.
  - **brand** (string) - The brand of the device.
  - **model** (string) - The model of the device.
  - **os** (string) - The operating system of the device.
  - **os_version** (string) - The version of the operating system.
- **pagination** (object) - Pagination details for the response.
  - **count** (integer) - The number of items in the current response.
  - **has_more** (boolean) - Indicates if there are more items available.
  - **total_estimated** (integer) - The estimated total number of items.
  - **offset** (integer) - The offset for pagination.
  - **limit** (integer) - The limit for pagination.
- **query_info** (object) - Information about the query.
  - **time_range** (object) - The time range of the query.
    - **start** (string) - The start time of the query.
    - **end** (string) - The end time of the query.
  - **data_scanned_mb** (integer) - The amount of data scanned in MB.
  - **query_time_ms** (integer) - The time taken for the query in milliseconds.
  - **source** (string) - The data source.

#### Response Example
```json
{
  "user_id": "user_123",
  "locations": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "timestamp": 1709564400000,
      "latitude": 33.4484,
      "longitude": -112.074,
      "horizontal_accuracy": 6.5,
      "vertical_accuracy": 3.2,
      "altitude": 331.2,
      "speed": 0,
      "bearing": 0,
      "type": "STATIONARY",
      "battery_level": 78,
      "battery_status": "Not Charging",
      "is_mock": false,
      "network_status": true,
      "tracking_mode": "PRECISE",
      "location_permission": true,
      "appId": "app_a1b2c3d4e5f6",
      "user_id": "user_123",
      "tz_offset": "-7",
      "id": "loc_9f8e7d6c5b4a",
      "brand": "Google",
      "model": "Pixel 8",
      "os": "android",
      "os_version": "14"
    }
  ],
  "pagination": {
    "count": 1,
    "has_more": true,
    "total_estimated": 186,
    "offset": 0,
    "limit": 100
  },
  "query_info": {
    "time_range": {
      "start": "2026-03-03T00:00:00.000Z",
      "end": "2026-03-03T23:59:59.999Z"
    },
    "data_scanned_mb": 0,
    "query_time_ms": 85,
    "source": "dynamodb"
  }
}
```

#### Error Response (400)
- **error** (string) - Error message indicating invalid input.
- **message** (string) - Detailed error message.

#### Error Response Example (400)
```json
{
  "error": "Invalid user_id",
  "message": "user_id is required and cannot be ANONYMOUS"
}
```

#### Error Response (401)
- **success** (boolean) - Indicates failure.
- **error** (string) - Error code for authentication failure.
- **code** (string) - Specific error code.
- **message** (string) - Detailed error message.

#### Error Response Example (401)
```json
{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": "AUTH_001",
  "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
}
```
```

--------------------------------

### Enable Background Tracking

Source: https://www.localsdk.com/docs/sdks/ios

Configure the SDK to enable background location updates after enabling the necessary project capabilities.

```swift
sdk.startTracking(mode: .adaptive, background: true)
```

--------------------------------

### List User Devices

Source: https://www.localsdk.com/docs/api-reference/user-location

Lists all devices associated with a user.

```APIDOC
## GET /api/v1/users/{user_id}/devices

### Description
List all devices associated with a user.

### Method
GET

### Endpoint
/api/v1/users/{user_id}/devices

### Parameters
#### Authorization
- **Authorization** (string) - Required - Bearer token for authentication. Format: `Bearer <api_key>`

#### Path Parameters
- **user_id** (string) - Required - User identifier. Cannot be "ANONYMOUS".

#### Query Parameters
- **active_only** (boolean) - Optional - Filter to active devices only (devices with a location newer than `max_age`). Defaults to `false`.
- **max_age** (integer) - Optional - Activity threshold in seconds. Devices with a location newer than this are considered active. Defaults to `86400`. Range: `0 <= value`.

### Request Example
```json
{
  "example": "curl -X GET \"https://api.localsdk.com/api/v1/users/user_123/devices\" \
  -H \"Authorization: Bearer <api_key>\""
}
```

### Response
#### Success Response (200)
- **user_id** (string) - The ID of the user.
- **device_count** (integer) - The total number of devices associated with the user.
- **devices** (array) - An array of device objects.
  - **device_id** (string) - The unique identifier for the device.
  - **last_seen** (integer) - The timestamp when the device was last seen.
  - **last_location** (object) - The last known location of the device.
    - **latitude** (number) - The latitude coordinate.
    - **longitude** (number) - The longitude coordinate.
    - **timestamp** (integer) - The timestamp of the last location.
  - **battery_level** (integer) - The current battery level of the device.
  - **battery_status** (string) - The status of the device's battery (e.g., "Not Charging").
  - **network_status** (boolean) - Indicates the network connectivity status of the device.
  - **model** (string) - The model name of the device.
  - **os_version** (string) - The operating system version of the device.

#### Response Example
```json
{
  "user_id": "user_123",
  "device_count": 2,
  "devices": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "last_seen": 1709564400000,
      "last_location": {
        "latitude": 33.4484,
        "longitude": -112.074,
        "timestamp": 1709564400000
      },
      "battery_level": 78,
      "battery_status": "Not Charging",
      "network_status": true,
      "model": "Pixel 8",
      "os_version": "14"
    },
    {
      "device_id": "82g6504d51fb36943h07g846",
      "last_seen": 1709563200000,
      "last_location": {
        "latitude": 33.4255,
        "longitude": -111.94,
        "timestamp": 1709563200000
      },
      "battery_level": 55,
      "battery_status": "Not Charging",
      "network_status": true,
      "model": "iPhone 15",
      "os_version": "17.2"
    }
  ]
}
```

#### Error Response (400)
- **error** (string) - Error message indicating invalid input.
- **message** (string) - Detailed error message.

#### Error Response Example (400)
```json
{
  "error": "Invalid user_id",
  "message": "user_id is required and cannot be ANONYMOUS"
}
```

#### Error Response (401)
- **success** (boolean) - Indicates failure.
- **error** (string) - Error code for authentication failure.
- **code** (string) - Specific error code.
- **message** (string) - Detailed error message.

#### Error Response Example (401)
```json
{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": "AUTH_001",
  "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
}
```
```

--------------------------------

### Get Current User Location

Source: https://www.localsdk.com/docs/api-reference/user-location

Retrieve the latest positions for all devices owned by a specific user. Ensure the Authorization header includes your Bearer token.

```cURL
curl -X GET "https://api.localsdk.com/api/v1/users/user_123/locations/current?timezone=America%2FPhoenix" \
  -H "Authorization: Bearer "
```

--------------------------------

### Get User Location History

Source: https://www.localsdk.com/docs/api-reference/user-location

Access historical position data for all devices owned by a specific user. The `distance_travelled` parameter is only supported for single-day queries.

```API
GET /api/v1/users/{user_id}/locations/history
```

--------------------------------

### Current location — all devices

Source: https://www.localsdk.com/docs/api-reference/current-location

Fetch the latest positions across all devices associated with your application, with options for pagination and filtering.

```APIDOC
## Current location — all devices

### Description
Fetch the latest positions across all devices associated with your app.

### Method
GET

### Endpoint
`/api/v1/locations/current`

### Authorization
`BearerAuth`
Authorization: Bearer <token>
API key obtained from the LocalSDK admin panel. Pass as: `Authorization: Bearer <api_key>`
In: `header`

### Query Parameters
- **limit** (integer) - Optional - Number of results to return. Default: `100`. Range: `1 <= value <= 1000`.
- **offset** (integer) - Optional - Pagination offset. Default: `0`. Range: `0 <= value`.
- **timestamp_after** (integer) - Optional - Filter locations after this Unix timestamp (milliseconds).
- **timestamp_before** (integer) - Optional - Filter locations before this Unix timestamp (milliseconds).
- **timezone** (string) - Optional - Timezone for timestamp conversion. Accepts: IANA names, UTC offsets, Abbreviations.

### Response
#### Success Response (200)
- **success** (boolean)
- **app_id** (string)
- **locations** (array)
  - **device_id** (string)
  - **app_id** (string)
  - **timestamp** (integer)
  - **latitude** (number)
  - **longitude** (number)
  - **horizontal_accuracy** (number)
  - **vertical_accuracy** (number)
  - **altitude** (number)
  - **speed** (number)
  - **bearing** (number)
  - **type** (string)
  - **battery_level** (integer)
  - **battery_status** (string)
  - **network_status** (boolean)
  - **location_permission** (boolean)
  - **is_mock** (boolean)
  - **tracking_mode** (string)
  - **tz_offset** (string)
  - **user_id** (string)
- **pagination** (object)
  - **count** (integer)
  - **has_more** (boolean)
  - **total_count** (integer)
  - **offset** (integer)
  - **limit** (integer)

### Request Example
```json
{
  "locations": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "app_id": "app_a1b2c3d4e5f6",
      "timestamp": 1709564400000,
      "latitude": 33.4484,
      "longitude": -112.074,
      "horizontal_accuracy": 6.5,
      "vertical_accuracy": 3.2,
      "altitude": 331.2,
      "speed": 0,
      "bearing": 0,
      "type": "STATIONARY",
      "battery_level": 78,
      "battery_status": "Not Charging",
      "network_status": true,
      "location_permission": true,
      "is_mock": false,
      "tracking_mode": "PRECISE",
      "tz_offset": "-7",
      "user_id": "user_123"
    },
    {
      "device_id": "71f5493c40ea25832g96f735",
      "app_id": "app_a1b2c3d4e5f6",
      "timestamp": 1709564380000,
      "latitude": 40.7128,
      "longitude": -74.006,
      "horizontal_accuracy": 4.1,
      "vertical_accuracy": 2.8,
      "altitude": 10.8,
      "speed": 12.5,
      "bearing": 87,
      "type": "MOVING",
      "battery_level": 42,
      "battery_status": "Charging",
      "network_status": true,
      "location_permission": true,
      "is_mock": false,
      "tracking_mode": "PRECISE",
      "tz_offset": "-5",
      "user_id": "user_456"
    }
  ],
  "pagination": {
    "count": 2,
    "has_more": false,
    "total_count": 2,
    "offset": 0,
    "limit": 100
  }
}
```
```

--------------------------------

### Get Location History

Source: https://www.localsdk.com/docs/api-reference/location-history

Query historical positions across all devices associated with your app. You can filter results by date range, minimum accuracy, and timezone.

```APIDOC
## GET /api/v1/locations/history

### Description
Query historical positions across all devices associated with your app.

### Method
GET

### Endpoint
`/api/v1/locations/history`

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - Start date in `YYYY-MM-DD` format. Defaults to today if omitted.
- **end_date** (string) - Optional - End date in `YYYY-MM-DD` format. Defaults to today if omitted.
- **limit** (integer) - Optional - Number of results per page. Default: `100`. Range: `1 <= value <= 1000`.
- **offset** (integer) - Optional - Number of results to skip for pagination. Default: `0`. Range: `0 <= value`.
- **min_accuracy** (number) - Optional - Filter by minimum accuracy in meters. Range: `0 <= value <= 1000`.
- **timezone** (string) - Optional - Timezone for timestamp conversion. Accepts IANA names, UTC offsets, or abbreviations.

### Authorization
`BearerAuth`
Authorization: Bearer <token>
API key obtained from the LocalSDK admin panel. Pass as: `Authorization: Bearer <api_key>`
In: `header`

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **app_id** (string) - The ID of the application.
- **locations** (array) - An array of location objects.
  - **device_id** (string) - The ID of the device.
  - **timestamp** (integer) - The timestamp of the location in milliseconds since epoch.
  - **latitude** (number) - The latitude of the location.
  - **longitude** (number) - The longitude of the location.
  - **horizontal_accuracy** (number) - The horizontal accuracy in meters.
  - **altitude** (number) - The altitude in meters.
  - **speed** (number) - The speed in meters per second.
  - **bearing** (number) - The bearing in degrees.
  - **type** (string) - The type of location (e.g., 'STATIONARY', 'MOVING').
  - **battery_level** (integer) - The battery level of the device.
  - **battery_status** (string) - The battery status of the device.
  - **appId** (string) - The ID of the application.
  - **user_id** (string) - The ID of the user.
  - **id** (string) - The unique ID of the location record.
- **pagination** (object) - Pagination details.
  - **count** (integer) - The number of results on the current page.
  - **has_more** (boolean) - Indicates if there are more results available.
  - **total_devices** (integer) - The total number of devices queried.
- **query_info** (object) - Information about the query.
  - **time_range** (object) - The time range of the query.
    - **start** (string) - The start of the time range.
    - **end** (string) - The end of the time range.
  - **devices_queried** (integer) - The number of devices queried.
  - **data_scanned_mb** (number) - The amount of data scanned in megabytes.
  - **query_time_ms** (integer) - The time taken for the query in milliseconds.

### Request Example
```json
{
  "locations": [
    {
      "device_id": "68e4382b39d914721f85e624",
      "timestamp": 1709564400000,
      "latitude": 33.4484,
      "longitude": -112.074,
      "horizontal_accuracy": 6.5,
      "altitude": 331.2,
      "speed": 0,
      "bearing": 0,
      "type": "STATIONARY",
      "battery_level": 78,
      "battery_status": "Not Charging",
      "appId": "app_a1b2c3d4e5f6",
      "user_id": "user_123",
      "id": "loc_9f8e7d6c5b4a"
    }
  ],
  "pagination": {
    "count": 2,
    "has_more": true,
    "total_devices": 15
  },
  "query_info": {
    "time_range": {
      "start": "2026-03-04T00:00:00.000Z",
      "end": "2026-03-04T23:59:59.999Z"
    },
    "devices_queried": 15,
    "data_scanned_mb": 5.47,
    "query_time_ms": 520
  }
}
```

### Error Responses
- **400 Bad Request** - Invalid timezone provided.
  ```json
  {
    "success": false,
    "message": "Invalid timezone: Invalid/Zone"
  }
  ```
- **401 Unauthorized** - Missing or invalid API key.
  ```json
  {
    "success": false,
    "error": "MISSING_API_KEY",
    "code": "AUTH_001",
    "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
  }
  ```
- **403 Forbidden** - Insufficient permissions.
  ```json
  {
    "success": false,
    "error": "INSUFFICIENT_PERMISSIONS",
    "code": "AUTH_005",
    "message": "Permission 'read' is required for this endpoint"
  }
  ```
- **404 Not Found** - Device not found or does not belong to your app.
  ```json
  {
    "success": false,
    "device_id": "68e4382b39d914721f85e624",
    "locations": [],
    "pagination": {
      "count": 0,
      "has_more": false
    },
    "query_info": {
      "time_range": {
        "start": "2026-03-03",
        "end": "2026-03-03"
      },
      "data_scanned_mb": 0,
      "query_time_ms": 0
    },
    "message": "Device not found or does not belong to your app"
  }
  ```
```