--- title: "Historical Vehicle Locations" method: GET path: "/vehicles/{vehicleId}/locations" tags: ["Vehicles"] --- # Historical Vehicle Locations `GET /vehicles/{vehicleId}/locations` ## Request - Base URL: `https://api.withterminal.com/tsp/v1` - URL: `https://api.withterminal.com/tsp/v1/vehicles/{vehicleId}/locations` - Auth: HTTP bearer List the historical breadcrumb locations for a vehicle. _Note:_ Given the large volume of location data available, we encourage customers to accept compressed (`gzip`) responses in order to maximize throughput. This is supported with many popular HTTP clients. Result limits vary depending on if results are compressed or not. ## Query parameters - `cursor` string, cursor - `limit` integer - `startAt` string, date-time - `endAt` string, date-time - `raw` boolean ## Headers - `X-Application-Id` string - `Connection-Token` string, required ## Response `200` OK - object - `results` VehicleLocation[], required - `id` string, ulid, required: Unique identifier for the vehicle location in Terminal. - `sourceId` string: The ID used to represent the entity in the source system. - `provider` string, required: Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers). - `vehicle` union, required - string, ulid: Unique identifier for the vehicle in Terminal. - ExpandedVehicle - `id` string, ulid, required: Unique identifier for the vehicle in Terminal. - `sourceId` string, required: The ID used to represent the entity in the source system. - `provider` string, required: Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers). - `status` 'active' | 'inactive', required: The status in the providers system - `vin` string - `name` string - `make` string - `model` string - `year` integer - `groups` GroupId[]: The groups the vehicle belongs to. - `devices` DeviceId[]: The devices installed in the vehicle. - `licensePlate` object - `state` 'AL' | 'AK' | 'AS' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'GU' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MP' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'VI' | 'AB' | 'BC' | 'MB' | 'NB' | 'NL' | 'NS' | 'ON' | 'PE' | 'QC' | 'SK' | 'NT' | 'NU' | 'UM' | 'YT' | 'DC': US State or Canadian Province - `number` string - `fuelType` 'gasoline' | 'diesel' | 'propane' | 'electric' | 'hybrid_gasoline' | 'hybrid_diesel' | 'biodiesel' | 'compressed_natural_gas' | 'liquefied_natural_gas' | 'ethanol' | 'hydrogen' | 'plug_in_hybrid' - `fuelEfficiency` number: This field will be removed in the future as is not commonly available from providers. - `fuelTankCapacity` number: Maximum amount of fuel vehicle can hold in liters. - `createdAt` string, date-time: The date and time the record was created in the provider's system. This timestamp comes directly from the source system and represents when the data was originally created there. Note: not all providers expose this. - `updatedAt` string, date-time: The date and time the record was updated in the provider's system. This timestamp comes directly from the source system and represents when the data was last updated there. Note: not all providers expose this. - `metadata` CoreEntityMetadata, required: Internal metadata about the record. - `addedAt` string, date-time, required: The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider's system. - `modifiedAt` string, date-time, required: The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system. - `deletedAt` string, date-time: The date and time the record was deleted from Terminal. Note: this is not the date and time the record was deleted in the provider's system. - `visibility` 'visible' | 'hidden_by_exclude_list' | 'hidden_by_include_list' | 'hidden_by_status' | 'deleted': Visibility status of a resource. Read more about hidden records [here](https://docs.withterminal.com/guides/vehicle-driver-filtering). - `raw` RawData[] - `provider` string, required - `schema` string, required - `extractedAt` string, required - `data` object, required - `driver` union - string, ulid: Unique identifier for the driver in Terminal. - ExpandedDriver - `id` string, ulid, required: Unique identifier for the driver in Terminal. - `sourceId` string, required: The ID used to represent the entity in the source system. - `provider` string, required: Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers). - `status` 'active' | 'inactive', required: The status in the providers system - `firstName` string - `middleName` string - `lastName` string - `email` string, email - `phone` string: Phone number formatted in [E.164](https://www.twilio.com/docs/glossary/what-e164) formatting - `username` string: The driver's username for login purposes - `license` object - `state` 'AL' | 'AK' | 'AS' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'GU' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MP' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'VI' | 'AB' | 'BC' | 'MB' | 'NB' | 'NL' | 'NS' | 'ON' | 'PE' | 'QC' | 'SK' | 'NT' | 'NU' | 'UM' | 'YT' | 'DC': US State or Canadian Province - `number` string - `groups` GroupId[]: The groups the driver belongs to. - `createdAt` string, date-time: The date and time the record was created in the provider's system. This timestamp comes directly from the source system and represents when the data was originally created there. Note: not all providers expose this. - `updatedAt` string, date-time: The date and time the record was updated in the provider's system. This timestamp comes directly from the source system and represents when the data was last updated there. Note: not all providers expose this. - `metadata` CoreEntityMetadata, required: Internal metadata about the record. - `addedAt` string, date-time, required: The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider's system. - `modifiedAt` string, date-time, required: The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system. - `deletedAt` string, date-time: The date and time the record was deleted from Terminal. Note: this is not the date and time the record was deleted in the provider's system. - `visibility` 'visible' | 'hidden_by_exclude_list' | 'hidden_by_include_list' | 'hidden_by_status' | 'deleted': Visibility status of a resource. Read more about hidden records [here](https://docs.withterminal.com/guides/vehicle-driver-filtering). - `raw` RawData[] - `provider` string, required - `schema` string, required - `extractedAt` string, required - `data` object, required - `locatedAt` string, date-time, required: [ISO 8601](https://www.w3.org/TR/NOTE-datetime) date - `location` Coordinates, required - `longitude` number, required - `latitude` number, required - `address` object: Reverse geocoded address details for locations when available at the source. - `formatted` string - `heading` number: Heading in degrees - `speed` number: Speed in KPH rounded to 2 decimal places. - `metadata` TimeSeriesMetadata, required: Internal metadata about the time series. - `modifiedAt` string, date-time, required: The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system. - `raw` RawData[] - `provider` string, required - `schema` string, required - `extractedAt` string, required - `data` object, required - `next` string, cursor: Cursor used for pagination. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `410`: Gone - `429`: Too Many Requests - `500`: Internal Server Error ## Changes - **2026-11-03** `71081936e1bd`: 1 breaking, 4 info - added the pattern `^[A-Za-z0-9+/=_-]+$` to the `query` request parameter `cursor` - added the non-success response with the status `410` - added `#/components/schemas/BaseVehicleLocation` to the `results/items/` response property `allOf` list for the response status `200` - removed `subschema #2: Base Vehicle Location` from the `results/items/` response property `allOf` list for the response status `200` - …1 more [Operation history](https://skmtc.dev/withterminal/apis/terminal-telematics-api/changes/vehicles/:vehicleId/locations/get.md) --- [API](https://skmtc.dev/withterminal/apis/terminal-telematics-api.md) - [All operations](https://skmtc.dev/withterminal/apis/terminal-telematics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withterminal/apis/terminal-telematics-api/revisions/a9f825034fd3?raw)