Location History Queries

The GraphQL API provides several queries for retrieving location history data for trackers.

recentLocationHistory

Retrieves the most recent location history entries, with optional filtering by brand, production run, and tracker status.

Parameters

Parameter	Type	Description
limit	Int	Maximum number of entries to return (default: 10)
brandId	ID	Filter by specific brand ID
productionRunIds	[ID!]	Filter by list of production run IDs
currentStatuses	[TrackerStatus!]	Filter by list of tracker statuses

Returns

A list of LocationHistory objects, ordered by timestamp (descending).

Example

query {
  recentLocationHistory(
    limit: 5
    brandId: "1"
    productionRunIds: ["42", "43"]
    currentStatuses: [IN_TRANSIT, DELIVERED]
  ) {
    id
    timestamp
    location {
      latitude
      longitude
    }
    nearestCity
    confidence
    horizontalAccuracy
    tracker {
      id
      name
      currentStatus
    }
  }
}

locationHistoryByTracker

Retrieves all location history entries for a specific tracker.

Parameters

Parameter	Type	Description
trackerId	ID!	ID of the tracker to get location history for

Returns

A list of LocationHistory objects for the specified tracker.

Example

query {
  locationHistoryByTracker(trackerId: "123") {
    id
    timestamp
    location {
      latitude
      longitude
    }
    nearestCity
    confidence
    horizontalAccuracy
  }
}

locationHistoryByTimeRange

Retrieves location history entries for a specific tracker within a time range.

Parameters

Parameter	Type	Description
trackerId	ID!	ID of the tracker to get location history for
startTime	DateTime!	Start of the time range
endTime	DateTime!	End of the time range

Returns

A list of LocationHistory objects for the specified tracker within the time range.

Example

query {
  locationHistoryByTimeRange(
    trackerId: "123"
    startTime: "2025-04-21T00:00:00Z"
    endTime: "2025-04-28T23:59:59Z"
  ) {
    id
    timestamp
    location {
      latitude
      longitude
    }
    nearestCity
    confidence
    horizontalAccuracy
  }
}

locationHistoryAggregated

Retrieves aggregated location history data for a specific tracker within a time range, using the specified bucket size for aggregation.

Parameters

Parameter	Type	Description
trackerId	ID!	ID of the tracker to get location history for
startTime	DateTime!	Start of the time range
endTime	DateTime!	End of the time range
bucketSize	String	Size of the time buckets for aggregation. Options: "1 hour" or "1 day". Default: "1 hour"

Returns

A list of aggregated LocationHistory objects for the specified tracker within the time range.

Example

query {
  locationHistoryAggregated(
    trackerId: "123"
    startTime: "2025-04-21T00:00:00Z"
    endTime: "2025-04-28T23:59:59Z"
    bucketSize: "1 day"
  ) {
    id
    timestamp
    location {
      latitude
      longitude
    }
    nearestCity
    confidence
    horizontalAccuracy
  }
}

Notes

• All location history queries respect client permissions. Users can only access location history for trackers associated with their authorized clients.
• Location history records are filtered by default to only include medium to high confidence reports (confidence >= 2).
• The horizontalAccuracy field represents the accuracy radius in meters. Lower values indicate more precise location data.
• The confidence field uses a scale of 1-3 (1: Low, 2: Medium, 3: High).