Trip Search
Contents
Once a trip is created, you can use the Trip Search endpoint to retrieve trips by trip name, driver ID, vehicle ID, TMS trip ID, or planned start date range. Use this endpoint when you need to do an individual trip lookup or create trip lists based on filters such as driver ID or vehicle ID. Large results can be paginated.
GET /trips/search
Resource URL
https://tripmanagement.trimblemaps.com/api/trips/search
Request parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
name
| Trip name to search for. Maximum length is 50 characters. Longer names are truncated during Plan Trip.
|
string | No |
tspDriverId
| Driver identifier supplied by the TSP/customer system. |
string | No |
tspVehicleId
| Vehicle identifier supplied by the TSP/customer system. |
string | No |
tmsTripId
| Customer/TMS trip identifier. Use this for exact customer trip lookup. |
string | No |
startDate
| Start of the planned trip date/time search window. Use ISO-8601 format. If omitted, defaults to 30 days before the current time. |
date-time | No |
endDate
| End of the planned trip date/time search window. Use ISO-8601 format. If omitted, defaults to 15 days after the current time. |
date-time | No |
pageNumber
| Page number for paginated results. |
integer | No |
pageSize
| Maximum number of trips returned per page. Maximum value is 10.
|
integer | No |
How filters work
- Parameters are passed as query string filters.
- Single-field searches are supported for
name,tspDriverId,tspVehicleId, andtmsTripId. - Trip names are limited to
50characters. If a longer name is sent during Plan Trip, it is truncated. - Date range searches are supported with
startDateandendDate. - Maximum date range is
45days. - If no date range is supplied, the default window is
-30days to+15days from the current day and time. - - If no query parameters are passed, all trips within the default date range will be returned. - Combined searches are supported by passing multiple filters in the same request.
- Pagination is supported with
pageNumberandpageSize. - A no-match search returns HTTP
200with an emptydataarray.
Example requests
Search by a single field (trip name)
GET https://tripmanagement.trimblemaps.com/api/trips/search?name={name}
Authorization: {apiKey}
Content-Type: application/json
Search by multiple fields
GET https://tripmanagement.trimblemaps.com/api/trips/search?name={name}&tspDriverId={driverId}&tspVehicleId={vehicleId}&tmsTripId={tmsTripId}&startDate={startDate}&endDate={endDate}&pageNumber=1&pageSize=10
Authorization: {apiKey}
Content-Type: application/json
Search by planned date range
GET https://tripmanagement.trimblemaps.com/api/trips/search?startDate={startDate}&endDate={endDate}
Authorization: {apiKey}
Content-Type: application/json
Paginated search
GET https://tripmanagement.trimblemaps.com/api/trips/search?pageNumber=1&pageSize=10
Authorization: {apiKey}
Content-Type: application/json
Response fields
| Field | Description | Type |
|---|---|---|
data
| Array of trip records matching the supplied filters. Empty when no trips match. |
array |
pageNumber
| Current page number, when pagination metadata is returned. |
integer |
pageSize
| Requested page size, when pagination metadata is returned. |
integer |
totalCount
| Total matching records, when pagination metadata is returned. |
integer |
Use cases
- Use
tmsTripIdfor exact trip lookup and reconciliation. - Use
tspDriverIdfor driver-based workflows. - Use
tspVehicleIdfor asset or vehicle-based workflows. - Use
startDateandendDateto bound broad searches. - Always include
pageNumberandpageSizefor UI and batch integrations.
Sample request
GET https://tripmanagement.trimblemaps.com/api/trips/search?tmsTripId={tmsTripId}&pageNumber=1&pageSize=10
Authorization: {apiKey}
Content-Type: application/json
Sample response
{
"data": [
{
"accountName": "tripmgt_test",
"tripStatus": "Planned",
"modifiedOn": "2026-08-06T14:39:22+00:00",
"tripDistance": 5917.346,
"tripDriveDuration": 6003.583,
"tripDuration": 13113.583,
"hoursOfServiceRemaining": {
"enabled": true,
"remainingDriveTimeUntilBreak": 26640.0,
"remainingDriveTime": 9480.0,
"remainingOnDutyTime": 18480.0,
"hoSRuleType": "USFed607LH",
"remainingCycleDutyTime": 184080.0,
"cycleTimeGains": [
42240.0,
48600.0,
10680.0,
37920.0,
38760.0,
38940.0
],
"lastCycleResetDateTime": null,
"last24HourBreakDateTime": "2026-08-11T06:57:59+00:00",
"remainingCanadaOnDutyTime": 20280.0,
"remainingDriveTimeUntilBreakDriver2": null,
"remainingDriveTimeDriver2": null,
"remainingOnDutyTimeDriver2": null,
"remainingCycleDutyTimeDriver2": null,
"cycleTimeGainsDriver2": null,
"lastCycleResetDateTimeDriver2": null,
"last24HourBreakDateTimeDriver2": null,
"remainingCanadaOnDutyTimeDriver2": null,
"alternateHoSRuleType": null,
"remainingTimeUntilFullDayBreak": 0.0,
"remainingTimeUntilFullDayBreakDriver2": null,
"remainingDrivingTimeInWeek": 0.0,
"remainingOnDutyTimeInDay": 0.0,
"remainingConsecutiveDrivingTime": 0.0,
"remainingFortnightlyTime": 0.0,
"currentOffDutyTime": null,
"currentOffDutyTimeDriver2": null
},
"url": "https://tripmanagement.alk.com/trip-viewer/token/m5usn8xcl9wkg6fgfjpclkljdrohxwcq2qj7947tmu/details/12106986?region=NA",
"tripCost": 12053.23,
"tripTolls": 0.0,
"actualTripTolls": null,
"planned": {
"tripDuration": 13113.583,
"tripCost": 12053.23,
"tripDistance": 5917.346
},
"remainingLegDistance": 0.0,
"remainingLegDriveDuration": 0.0,
"tmsTripId": "SOSEARCH1001",
"name": "search-test-alpha",
"stops": [
{
"plannedETA": "2026-08-06T10:39:21-04:00",
"currentETA": "2026-08-06T10:39:21-04:00",
"currentETD": "2026-08-06T10:39:21-04:00",
"earliestArrivalTime": "2020-06-19T09:00:00-04:00",
"latestArrivalTime": "2020-06-19T10:00:00-04:00",
"plannedDuration": 0.0,
"actualDuration": 0.0,
"plannedDepartureTime": "2026-08-06T10:39:21-04:00",
"stopStatus": "Open",
"stopArrivalStatus": "Late",
"atRiskThreshold": 15,
"tooEarlyThreshold": null,
"legDistance": 0.0,
"legDriveDuration": 0.0,
"metadata": null,
"amenities": null,
"truckServices": false,
"alternateRestStops": null,
"poiId": 0,
"setId": 0,
"persistentId": 0,
"activeDriver": 1,
"stopId": 116427610,
"slackTime": 0.0,
"location": {
"address": {
"StreetAddress": "360 Nassau Street (NJ-27)",
"city": "Princeton",
"state": "NJ",
"zip": "08540",
"county": "Mercer",
"country": "United States"
},
"coords": {
"lat": "40.354904",
"lon": "-74.645018"
},
"label": ""
},
"waypoint": false,
"stopSequence": 0,
"stopType": "Origin"
},
{
"plannedETA": "2026-08-06T17:45:24-04:00",
"currentETA": "2026-08-06T17:45:24-04:00",
"currentETD": "2026-08-06T18:15:24-04:00",
"earliestArrivalTime": "2026-08-06T17:30:24-04:00",
"latestArrivalTime": "2026-08-06T18:00:24-04:00",
"plannedDuration": 30.0,
"actualDuration": 0.0,
"plannedDepartureTime": "2026-08-06T18:15:24-04:00",
"stopStatus": "Open",
"stopArrivalStatus": "OnTime",
"atRiskThreshold": 10,
"tooEarlyThreshold": null,
"legDistance": 353.712,
"legDriveDuration": 426.05,
"metadata": null,
"amenities": [
"Fuel",
"DEF",
"Twentyfour_hour",
"Ten_HourParking",
"NumTruckParkingSpaces: 640",
"Showers",
"Scale",
"TruckRepair",
"TireService",
"PermitServices",
"RoadsideAssistance",
"ATM",
"Laundry",
"Restaurant",
"Restrooms"
],
"truckServices": true,
"alternateRestStops": null,
"poiId": 8769,
"setId": 13,
"persistentId": 697567,
"activeDriver": 1,
"stopId": 116427611,
"slackTime": 0.0,
"location": {
"address": {
"StreetAddress": "2440 Raphine Road",
"city": "Raphine",
"state": "VA",
"zip": "24472",
"county": null,
"country": "United States"
},
"coords": {
"lat": "37.929749",
"lon": "-79.228986"
},
"label": "@Orchard Creek Auto/RV Plaza"
},
"waypoint": false,
"stopSequence": 1,
"stopType": "RestStopShort"
},
{
"plannedETA": "2026-08-06T21:32:58-04:00",
"currentETA": "2026-08-06T21:32:58-04:00",
"currentETD": "2026-08-07T07:32:58-04:00",
"earliestArrivalTime": "2026-08-06T21:17:58-04:00",
"latestArrivalTime": "2026-08-06T21:47:58-04:00",
"plannedDuration": 600.0,
"actualDuration": 0.0,
"plannedDepartureTime": "2026-08-07T07:32:58-04:00",
"stopStatus": "Open",
"stopArrivalStatus": "OnTime",
"atRiskThreshold": 10,
"tooEarlyThreshold": null,
"legDistance": 195.435,
"legDriveDuration": 197.567,
"metadata": null,
"amenities": [
"Fuel",
"ATM",
"HotelNearby"
],
"truckServices": true,
"alternateRestStops": null,
"poiId": 4466,
"setId": 13,
"persistentId": 701307,
"activeDriver": 1,
"stopId": 116427612,
"slackTime": 0.0,
"location": {
"address": {
"StreetAddress": "15324 Lee Hwy",
"city": "Bristol",
"state": "VA",
"zip": "24202",
"county": null,
"country": "United States"
},
"coords": {
"lat": "36.65134",
"lon": "-82.08798"
},
"label": "@Quick Stop #36"
},
"waypoint": false,
"stopSequence": 2,
"stopType": "RestStopLong"
},
{
"plannedETA": "2026-08-07T14:00:42-05:00",
"currentETA": "2026-08-07T14:00:42-05:00",
"currentETD": "2026-08-07T14:30:42-05:00",
"earliestArrivalTime": "2026-08-07T13:45:42-05:00",
"latestArrivalTime": "2026-08-07T14:15:42-05:00",
"plannedDuration": 30.0,
"actualDuration": 0.0,
"plannedDepartureTime": "2026-08-07T14:30:42-05:00",
"stopStatus": "Open",
"stopArrivalStatus": "OnTime",
"atRiskThreshold": 10,
"tooEarlyThreshold": null,
"legDistance": 422.636,
"legDriveDuration": 447.733,
"metadata": null,
"amenities": null,
"truckServices": true,
"alternateRestStops": null,
"poiId": 4323,
"setId": 13,
"persistentId": 1993247,
"activeDriver": 1,
"stopId": 116427613,
"slackTime": 0.0,
"location": {
"address": {
"StreetAddress": "4001 Buttermilk Road",
"city": "Cottondale",
"state": "AL",
"zip": "35453",
"county": null,
"country": "United States"
},
"coords": {
"lat": "33.171136",
"lon": "-87.44573"
},
"label": "@Quik Trip #7170"
},
"waypoint": false,
"stopSequence": 3,
"stopType": "RestStopShort"
},
{
"plannedETA": "2026-08-07T17:35:43-05:00",
"currentETA": "2026-08-07T17:35:43-05:00",
"currentETD": "2026-08-08T03:35:43-05:00",
"earliestArrivalTime": "2026-08-07T17:20:43-05:00",
"latestArrivalTime": "2026-08-07T17:50:43-05:00",
"plannedDuration": 600.0,
"actualDuration": 0.0,
"plannedDepartureTime": "2026-08-08T03:35:43-05:00",
"stopStatus": "Open",
"stopArrivalStatus": "OnTime",
"atRiskThreshold": 10,
"tooEarlyThreshold": null,
"legDistance": 189.524,
"legDriveDuration": 185.017,
"metadata": null,
"amenities": [
"Fuel",
"Twentyfour_hour",
"Ten_HourParking",
"ATM",
"Restrooms"
],
"truckServices": true,
"alternateRestStops": null,
"poiId": 4283,
"setId": 13,
"persistentId": 701952,
"activeDriver": 1,
"stopId": 116427614,
"slackTime": 0.0,
"location": {
"address": {
"StreetAddress": "4050 Highway 11 South",
"city": "Hattiesburg",
"state": "MS",
"zip": "39402",
"county": null,
"country": "United States"
},
"coords": {
"lat": "31.256445",
"lon": "-89.338157"
},
"label": "@Circle K"
},
"waypoint": false,
"stopSequence": 4,
"stopType": "RestStopLong"
},
{
"plannedETA": "2026-08-08T10:30:41-05:00",
"currentETA": "2026-08-08T10:30:41-05:00",
"currentETD": "2026-08-08T10:30:41-05:00",
"earliestArrivalTime": "2020-06-20T08:00:00-05:00",
"latestArrivalTime": "2020-06-20T09:00:00-05:00",
"plannedDuration": 0.0,
"actualDuration": 0.0,
"plannedDepartureTime": "2026-08-08T10:30:41-05:00",
"stopStatus": "Open",
"stopArrivalStatus": "Late",
"atRiskThreshold": 15,
"tooEarlyThreshold": null,
"legDistance": 428.658,
"legDriveDuration": 414.967,
"metadata": null,
"amenities": null,
"truckServices": false,
"alternateRestStops": null,
"poiId": 0,
"setId": 0,
"persistentId": 0,
"activeDriver": 1,
"stopId": 116427615,
"slackTime": 0.0,
"location": {
"address": {
"StreetAddress": "343 Louisiana Street",
"city": "Houston",
"state": "TX",
"zip": "77002",
"county": "Harris",
"country": "United States"
},
"coords": {
"lat": "29.76334",
"lon": "-95.363382"
},
"label": "Houston City Center"
},
"waypoint": false,
"stopSequence": 5,
"stopType": "Work"
}]
}