Developer API
Developer APICore ConceptsLocations & History

Locations & History

Location data structure, accuracy, and historical tracking

Location Overview

TagLogger reports AirTag locations as latitude/longitude coordinates with a timestamp and an accuracy estimate. Historical points are retained so you can review where a tag has been over time.

Current location is available via GET /v1/tags/{tagId}/location (response: { "data": point | null, "recordingPaused": boolean }), while historical data is accessible through GET /v1/tags/{tagId}/history (response: { "data": [ ...points ], "nextCursor": string | null, "recordingPaused": boolean }). Both carry the full location point shape shown below; on the current-location response data is null when there is no fix or recording is paused. The summary on a tag object (tag.lastLocation) carries lat, lng, timestamp, and timestampMs.

Location Point

{
  "lat": 40.7128,
  "lng": -74.0060,
  "timestamp": "2024-06-19T13:45:23Z",
  "timestampMs": 1718809523000,
  "endTimestampMs": 1718809583000,
  "sampleCount": 3,
  "accuracy": 25,
  "altitude": 12.4,
  "verticalAccuracy": 4,
  "floorLevel": null,
  "isInaccurate": false,
  "isOld": false,
  "locationFinished": true,
  "battery": { "level": null, "status": 1 }
}

Fields

lat, lng

Latitude and longitude in decimal degrees (WGS84).

timestamp, timestampMs

When the location was recorded, as an ISO 8601 string and as epoch milliseconds. timestampMs is the authoritative ordering key.

endTimestampMs, sampleCount

Identical repeated sightings may be represented by one point. endTimestampMs is the end of that sighting window and sampleCount is the number of raw sightings it represents. For a single sighting they equal timestampMs and 1, respectively.

accuracy

Horizontal accuracy radius in meters. Lower values indicate higher precision. May be null.

altitude, verticalAccuracy, floorLevel

Optional vertical context: altitude in meters, its accuracy in meters, and an indoor floor level when available. Any may be null.

isInaccurate, isOld, locationFinished

Quality flags. isInaccurate marks a low-confidence fix, isOld marks a stale fix, and locationFinished indicates the fix has settled.

battery

Battery state at the time of the fix. level is reserved and currently always null; status is the battery status: 0 unknown, 1 good, 2 medium, 3 low (an early warning, plan a swap), 4 critical (replace soon).

Current vs. Historical Location

Current location is the most recent reported point. Fetch it via:

GET /v1/tags/{tagId}/location

Historical location returns the points recorded in a time window. By default, when you omit start, the response is bounded to the last 7 days. To retrieve the complete trail, pass an explicit start. Fetch with optional filtering:

GET /v1/tags/{tagId}/history?start=2024-06-01T00:00:00Z&end=2024-06-30T23:59:59Z&limit=200

Query parameters: start (ISO 8601 or epoch ms, defaults to end minus 7 days), end (ISO 8601 or epoch ms, defaults to now), order (asc/desc, default asc), limit (default 200, max 1000), cursor (for pagination). An unfiltered call returns the last 7 days; pass an explicit start to retrieve the complete history.

Accuracy Interpretation

The accuracy field represents the estimated horizontal error radius. Lower values indicate higher confidence:

  • <10 meters: High precision.
  • 10–50 meters: Good precision.
  • 50–100 meters: Moderate precision.
  • >100 meters: Low precision (rough estimate).

Treat accuracy as an error radius around the reported point, and check isInaccurate / isOld when precision matters for your use case.

Recording Pause

When a tag's recording is paused (tag.recordingPaused is true), new points are not recorded and tag.lastLocation is null. While paused, no NEW points are recorded, but History still returns the existing trail. Responses for a paused tag include recordingPaused: true as an advisory flag.

This is useful for privacy (e.g., preventing tracking during sensitive trips) or for temporarily pausing a tag without deactivating it.

Data Retention

Historical location data is retained for your workspace for as long as the tag is active. To export the complete trail, page through GET /v1/tags/{tagId}/history with an explicit start (an unfiltered call returns only the last 7 days), following nextCursor to the end. To remove stored history, use the delete-history control on the tag in your dashboard.

Example: Fetching Location History

// Get the most recent points for a tag
const response = await fetch(
  'https://api.taglogger.com/v1/tags/aB3xK9Qm1Zr7/history?order=desc&limit=200',
  { headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);

const { data, nextCursor } = await response.json();

for (const point of data) {
  console.log(`At ${point.timestamp}: (${point.lat}, ${point.lng}) ±${point.accuracy}m`);
}

See Also