LocalSDK

User Location

User-scoped location and device endpoints

Current location — by user

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

GET
/api/v1/users/{user_id}/locations/current

Authorization

BearerAuth
AuthorizationBearer <token>

API key obtained from the LocalSDK admin panel. Pass as: Authorization: Bearer <api_key>

In: header

Path Parameters

user_id*string

User identifier. Cannot be "ANONYMOUS".

Query Parameters

max_age?integer

Maximum age of location in seconds.

Range0 <= value
accuracy?integer

Minimum accuracy requirement in meters (locations with horizontal_accuracy greater than this are excluded).

Range0 <= value
limit?integer

Number of results to return.

Default100
Range1 <= value <= 1000
timezone?string

Timezone for timestamp conversion. Accepts:

  • IANA names: America/Phoenix, Europe/London, Asia/Tokyo
  • UTC offsets: +05:30, -07:00
  • Abbreviations: PST, EST, CST, MST, UTC, GMT

Response Body

application/json

application/json

application/json

curl -X GET "https://api.localsdk.com/api/v1/users/user_123/locations/current?timezone=America%2FPhoenix"
{
  "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": "Invalid user_id",
  "message": "user_id is required and cannot be ANONYMOUS"
}

{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": "AUTH_001",
  "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
}

Location history — by user

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

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

Authorization

BearerAuth
AuthorizationBearer <token>

API key obtained from the LocalSDK admin panel. Pass as: Authorization: Bearer <api_key>

In: header

Path Parameters

user_id*string

User identifier. Cannot be "ANONYMOUS".

Query Parameters

start_date?string

Start date in YYYY-MM-DD format. Defaults to today if omitted.

Formatdate
end_date?string

End date in YYYY-MM-DD format. Defaults to today if omitted.

Formatdate
limit?integer

Number of results per page.

Default100
Range1 <= value <= 1000
offset?integer

Number of results to skip for pagination.

Default0
Range0 <= value
timezone?string

Timezone for timestamp conversion. Accepts:

  • IANA names: America/Phoenix, Europe/London, Asia/Tokyo
  • UTC offsets: +05:30, -07:00
  • Abbreviations: PST, EST, CST, MST, UTC, GMT
distance_travelled?string

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 Body

application/json

application/json

application/json

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"
{
  "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": "Invalid user_id",
  "message": "user_id is required and cannot be ANONYMOUS"
}

{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": "AUTH_001",
  "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
}

List user devices

List all devices associated with a user.

GET
/api/v1/users/{user_id}/devices

Authorization

BearerAuth
AuthorizationBearer <token>

API key obtained from the LocalSDK admin panel. Pass as: Authorization: Bearer <api_key>

In: header

Path Parameters

user_id*string

User identifier. Cannot be "ANONYMOUS".

Query Parameters

active_only?boolean

Filter to active devices only (devices with a location newer than max_age).

Defaultfalse
max_age?integer

Activity threshold in seconds. Devices with a location newer than this are considered active.

Default86400
Range0 <= value

Response Body

application/json

application/json

application/json

curl -X GET "https://api.localsdk.com/api/v1/users/user_123/devices"
{
  "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": "Invalid user_id",
  "message": "user_id is required and cannot be ANONYMOUS"
}

{
  "success": false,
  "error": "MISSING_API_KEY",
  "code": "AUTH_001",
  "message": "API key is required. Provide it in Authorization header as \"Bearer <api_key>\""
}

Location History

Query historical location data

Nearby Devices

Device management and discovery