> ## 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
> New endpoint for retrieving trailer location data with fleet filtering and time-based queries
**Released 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:**
```bash theme={null}
# 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:**
```json theme={null}
{
"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.
```bash theme={null}
# 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.
```bash theme={null}
# 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.
```bash theme={null}
# 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?
View complete endpoint documentation with current API structure
Questions about migrating your integration? Our team is here to help
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.