Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt

Use this file to discover all available pages before exploring further.

​
v2.4.0 - Trailer Location Tracking
20th January 2026
This minor release introduces trailer location tracking capabilities, enabling you to retrieve historical and current location data for trailers in your fleet.
Minor Release: This release adds a new endpoint and data model for trailer locations. All changes are backward-compatible with no breaking changes to existing integrations.

​
New Endpoint

A new GET /v2/telematics/trailer-locations endpoint provides access to trailer location data with comprehensive filtering options.Key Features:
  • Retrieve current or historical trailer locations
  • Filter by fleet, trailer, or time range
  • Optional latest-only mode for real-time tracking
  • Paginated responses with cursor-based navigation
Query Parameters:
  • only_latest (boolean, default: true) - Return only the most recent location per trailer
  • fleet_ids (array of UUIDs, max 100) - Filter by Catena fleet IDs
  • fleet_refs (array of strings, max 100) - Filter by your organization’s fleet references
  • trailer_ids (array of UUIDs, max 100) - Filter by specific trailers
  • from_datetime (ISO 8601) - Start of time range (default: now - 1 day)
  • to_datetime (ISO 8601) - End of time range (default: now)
  • include_source_data (boolean, default: false) - Include raw TSP data
  • cursor (string) - Pagination cursor
  • size (integer, default: 300, max: 1000) - Page size
Example Requests:
# Get latest location for all trailers
GET /v2/telematics/trailer-locations?only_latest=true

# Get historical locations for specific trailers
GET /v2/telematics/trailer-locations?only_latest=false&trailer_ids=550e8400-e29b-41d4-a716-446655440000&from_datetime=2026-01-19T00:00:00Z&to_datetime=2026-01-20T00:00:00Z

# Filter by fleet reference
GET /v2/telematics/trailer-locations?fleet_refs=FLEET_ABC&only_latest=true
When only_latest=true, the from_datetime and to_datetime query parameters are not applied. Only the most recent location per trailer is returned regardless of the date range specified.
Use only_latest=true for real-time fleet tracking dashboards, and only_latest=false with time filters for historical route analysis.

​
New Data Model

The new TrailerLocation schema provides comprehensive location data with full audit trail and source tracking.Core Fields:
  • id (UUID) - Unique identifier for the location record
  • trailer_id (UUID) - Internal Catena trailer identifier
  • location (GeoJSON Point | null) - Geographic coordinates
  • occurred_at (datetime) - When the location was recorded by the TSP
  • h3_index_11 (integer | null) - H3 geospatial index (resolution 11)
Fleet & Connection:
  • fleet_id (UUID) - Catena fleet identifier
  • connection_id (UUID) - Connection through which data was ingested
Source Tracking:
  • source_name (TspEnum) - Telematics service provider
  • source_id (string) - Unique identifier in the TSP system
  • source_trailer_id (string | null) - TSP’s trailer identifier
  • source_vehicle_id (string | null) - TSP’s vehicle identifier (if trailer is attached)
  • source_data (object) - Raw TSP payload (when include_source_data=true)
  • source_data_hash (string) - SHA-256 hash for deduplication
Audit Trail:
  • created_at (datetime) - When ingested into Catena
  • updated_at (datetime) - Last modification time
  • deleted_at (datetime | null) - Logical deletion timestamp
  • execution_id (UUID | null) - Execution that ingested this record
  • schedule_id (UUID | null) - Schedule that triggered ingestion
Example Response:
{
  "items": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "trailer_id": "550e8400-e29b-41d4-a716-446655440000",
      "fleet_id": "660e8400-e29b-41d4-a716-446655440001",
      "connection_id": "770e8400-e29b-41d4-a716-446655440002",
      "location": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
      },
      "h3_index_11": 622236750252466175,
      "occurred_at": "2026-01-20T14:30:00Z",
      "source_name": "samsara",
      "source_id": "trailer_loc_12345",
      "source_trailer_id": "TRL-001",
      "source_vehicle_id": null,
      "source_data_hash": "a3b2c1d4e5f6...",
      "created_at": "2026-01-20T14:35:00Z",
      "updated_at": "2026-01-20T14:35:00Z",
      "deleted_at": null,
      "execution_id": "880e8400-e29b-41d4-a716-446655440003",
      "schedule_id": "990e8400-e29b-41d4-a716-446655440004"
    }
  ],
  "next_page": "eyJjdXJzb3IiOiAiMjAyNi0wMS0yMFQxNDozMDowMFoifQ==",
  "previous_page": null,
  "current_page": "eyJjdXJzb3IiOiAiMjAyNi0wMS0yMFQxNTowMDowMFoifQ==",
  "current_page_backwards": "eyJjdXJzb3IiOiAiMjAyNi0wMS0yMFQxNDozMDowMFoiLCAiYmFja3dhcmRzIjogdHJ1ZX0="
}
The h3_index_11 field enables efficient geospatial queries and clustering. Use it for proximity searches or geographic aggregations.

​
Use Cases

Monitor current trailer locations across your fleet for operational visibility.
# Get latest location for all trailers in a specific fleet
GET /v2/telematics/trailer-locations?fleet_refs=FLEET_WEST&only_latest=true
Analyze trailer movement patterns and routes over time.
# Get 24-hour location history for a specific trailer
GET /v2/telematics/trailer-locations?trailer_ids=550e8400-e29b-41d4-a716-446655440000&only_latest=false&from_datetime=2026-01-19T00:00:00Z&to_datetime=2026-01-20T00:00:00Z
Combine location data with geospatial queries for zone monitoring.
# Get latest locations with source data for custom geofencing logic
GET /v2/telematics/trailer-locations?only_latest=true&include_source_data=true

​
Backward Compatibility

All changes in this release are backward-compatible:
  • New endpoint: GET /v2/telematics/trailer-locations is a net-new addition. No existing endpoints modified.
  • New schemas: TrailerLocation and pagination wrapper are new data models. No existing schemas changed.
  • No migration required: Existing integrations continue to work without any changes.
Security: Requires telematics:read scope (same as other telematics endpoints).

​
Need Help?

API Reference

View complete endpoint documentation with current API structure

Contact Support

Questions about migrating your integration? Our team is here to help