Location history — single device

Retrieve historical positions for a specific device with optional distance calculation. distance_travelled=true only works for single-day queries (start_date must equal end_date). Uses DynamoDB for data within the last 7 days, falls back to Athena/S3 for older data.

Authorization

BearerAuth

AuthorizationBearer <token>

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

In: header

Path Parameters

deviceId*string

Unique device identifier.

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

min_accuracy?number

Filter by minimum accuracy in meters (locations with horizontal_accuracy greater than this are excluded).

Range0 <= 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

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`

curl -X GET "https://api.localsdk.com/api/v1/devices/68e4382b39d914721f85e624/locations/history?start_date=2026-03-01&end_date=2026-03-03&timezone=America%2FPhoenix"

{
  "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
  }
}

{
  "success": false,
  "device_id": "68e4382b39d914721f85e624",
  "locations": [],
  "pagination": {
    "count": 0,
    "has_more": false
  },
  "query_info": {
    "time_range": {
      "start": "",
      "end": ""
    },
    "data_scanned_mb": 0,
    "query_time_ms": 0
  },
  "message": "Invalid timezone: Invalid/Zone"
}

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

{
  "success": false,
  "error": "INSUFFICIENT_PERMISSIONS",
  "code": "AUTH_005",
  "message": "Permission 'read' is required for this endpoint"
}

{
  "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"
}