Tracker Queries
Queries for retrieving tracker information and status.
tracker
Retrieves a single tracker by ID.
Arguments
type TrackerArgs {
"""
ID of the tracker to retrieve.
"""
id: ID!
}
Example Query
query GetTracker {
tracker(id: "123") {
id
name
currentStatus
advertisementKey
hashedAdvertisementKey
lastReportReceived
lastReportRequested
latestLocation {
timestamp
location {
latitude
longitude
}
nearestCity
}
productionRun {
id
description
brand {
id
name
}
}
}
}
trackers
Retrieves a list of all trackers the authenticated user has access to.
Example Query
query GetTrackers {
trackers {
id
name
currentStatus
latestLocation {
timestamp
location {
latitude
longitude
}
}
}
}
trackersByProductionRun
Retrieves all trackers associated with a specific production run.
Arguments
type TrackersByProductionRunArgs {
"""
ID of the production run.
"""
productionRunId: ID!
}
Example Query
query GetTrackersByProductionRun {
trackersByProductionRun(productionRunId: "123") {
id
name
currentStatus
latestLocation {
timestamp
location {
latitude
longitude
}
}
}
}
trackerByAdvertisementKey
Retrieves a tracker by its advertisement key.
Arguments
type TrackerByAdvertisementKeyArgs {
"""
Advertisement key of the tracker.
"""
key: String!
}
Example Query
query GetTrackerByAdvertisementKey {
trackerByAdvertisementKey(key: "abc123") {
id
name
currentStatus
advertisementKey
hashedAdvertisementKey
}
}
trackersConnection
Retrieves paginated trackers with filtering and ordering options.
Arguments
type TrackersConnectionArgs {
"""
Number of records to skip.
"""
offset: Int
"""
Maximum number of records to return.
"""
limit: Int
"""
Ordering options.
"""
orderBy: TrackerOrderBy
"""
Filter criteria.
"""
filters: TrackerFilters
}
input TrackerOrderBy {
"""
Field to order by.
"""
field: TrackerOrderField!
"""
Order direction.
"""
direction: OrderDirection!
}
enum TrackerOrderField {
NAME
TIMESTAMP
ID
STATUS
LOCATION
NEAREST_CITY
}
input TrackerFilters {
"""
Filter by brand ID.
"""
brandId: ID
"""
Filter by tracker statuses.
"""
currentStatuses: [TrackerStatus!]
"""
Filter by production run IDs.
"""
productionRunIds: [ID!]
}
Example Query
query GetTrackersPaginated {
trackersConnection(
offset: 0
limit: 10
orderBy: { field: TIMESTAMP, direction: DESC }
filters: { currentStatuses: [IN_TRANSIT], brandId: "123" }
) {
edges {
cursor
node {
id
name
currentStatus
latestLocation {
timestamp
location {
latitude
longitude
}
}
}
}
pageInfo {
hasNextPage
hasPreviousPage
}
totalCount
}
}
Error Handling
Common Errors
| Error Code | Description |
|---|---|
TRACKER_NOT_FOUND | Tracker ID not found |
INVALID_ADVERTISEMENT_KEY | Invalid advertisement key format |
PERMISSION_DENIED | Not authorized to view tracker |
Example Error Response
{
"errors": [
{
"message": "Tracker not found",
"extensions": {
"code": "TRACKER_NOT_FOUND",
"id": "123"
}
}
]
}
Best Practices
-
Authentication
- Always include valid JWT with client_list claim
- Handle token expiration gracefully
-
Real-time Updates
- Use Socket.IO for live tracker updates
- Subscribe to relevant tracker events
- Handle connection failures gracefully
-
Pagination
- Use offset/limit for predictable pagination
- Request appropriate page sizes
- Cache results when possible
-
Performance
- Request only needed fields
- Use appropriate filters
- Consider caching strategies
-
Error Handling
- Handle all error cases gracefully
- Implement retry logic where appropriate
- Provide meaningful error messages to users