# Retrieve Trips

Retrieve a list of all the trips in an organization or subset of an organization.

Endpoint: GET /v1/trips
Version: 1.0.0
Security: bearerAuth

## Query parameters:

  - `deviceIdentifier` (string)
    Filter by device identifier or serial number.
    Example: "5100FFFF-60B6-D7CD-3FA2-22CA712B0000"

  - `vehicleIdentifier` (string)
    Filter by vehicle identifier or VIN.
    Example: "5100DDDD-60B6-D7CD-3FA2-22CA712B0000"

  - `userIdentifier` (string)
    Filter by user identifier.
    Example: "5100CCCC-60B6-D7CD-3FA2-22CA712B0000"

  - `groupIdentifier` (string)
    Filter by group identifier.
    Example: "5100BBBB-60B6-D7CD-3FA2-22CA712B0000"

  - `startDate` (string)
    Filter by start date.
    Example: "2023-09-10T00:00:00Z"

  - `endDate` (string)
    Filter by end date.
    Example: "2023-09-30T23:59:59Z"

  - `offset` (integer)
    Record to start with.
    Example: 1

  - `limit` (integer)
    Number of records to return.
    Example: 100

  - `order` (string)
    Sort direction.
    Example: "asc"

  - `sort` (string)
    Name of property to sort on.
    Example: "EndDate"

  - `includeSubgroups` (boolean)
    Include subgroups.

## Response 200 fields (application/json):

  - `metadata` (object)

  - `metadata.limit` (integer)
    Example: 1

  - `metadata.count` (number)
    Example: 10

  - `metadata.offset` (integer)
    Example: 1

  - `metadata.startDate` (string)
    Example: "2023-09-10T00:00:00Z"

  - `metadata.endDate` (string)
    Example: "2023-09-30T23:59:59Z"

  - `data` (array,null)

  - `data.tripId` (string)

  - `data.startDate` (string)
    Example: "2023-09-10T08:00:00Z"

  - `data.endDate` (string)
    Example: "2023-09-10T08:45:00Z"

  - `data.creationDateTime` (string)
    Example: "2023-09-10T09:00:00Z"

  - `data.startPosition` (object,null)

  - `data.startPosition.latitude` (number)
    Latitude coordinate for the trip start position.
    Example: 32.887558

  - `data.startPosition.longitude` (number)
    Longitude coordinate for the trip start position.
    Example: -117.212288

  - `data.startPosition.address` (string)
    Start address for the trip.
    Example: "9785 Scranton Rd, San Diego, CA 92121"

  - `data.startPosition.occurrenceDateTime` (string)
    Date time for the trip start position.
    Example: "2023-09-10T08:00:00Z"

  - `data.startPosition.timezoneOffset` (number)
    Timezone offset for the trip start position.
    Example: -480

  - `data.endPosition` (object,null)

  - `data.endPosition.latitude` (number)
    Latitude coordinate for the trip end point.
    Example: 32.887558

  - `data.endPosition.longitude` (number)
    Longitude coordinate for the trip end point.
    Example: -117.212288

  - `data.endPosition.address` (string)
    End address for the trip.
    Example: "1600 Pacific Hwy, San Diego, CA 92101"

  - `data.endPosition.occurrenceDateTime` (string)
    Date time for the trip end position.
    Example: "2023-09-10T08:45:00Z"

  - `data.endPosition.timezoneOffset` (number)
    Timezone offset for the trip end position.
    Example: -480

  - `data.maxSpeedKph` (number)
    Max speed for the trip in kph
    Example: 55

  - `data.distanceKm` (number)
    Total kilometer distance traveled for the trip
    Example: 11

  - `data.deviceDistanceKm` (number,null)
    Trip distance in kilometers. Before July 10, 2026,  this value came directly from the device and could  differ slightly from distanceKm. Starting July 10, 2026,  this field returns the same value as distanceKm.
    Example: 11.4

  - `data.driver` (object,null)

  - `data.driver.id` (string)

  - `data.driver.firstName` (string)

  - `data.driver.lastName` (string)

  - `data.driver.employeeNumber` (string)

  - `data.vehicle` (object,null)

  - `data.vehicle.id` (string)
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `data.vehicle.imei` (string)
    Example: "6TJJS89"

  - `data.vehicle.serialNumber` (string)
    Example: "7365990"

  - `data.vehicle.vehicleName` (string)
    Example: "Toyota Tundra"

  - `data.vehicle.deviceId` (string)
    Example: "b2c3d4e5-f6a7-8901-bcde-f12345678901"

  - `data.vehicle.licensePlate` (string)
    Example: "7TMR879"

  - `data.vehicle.vin` (string)
    Example: "1HGCM82633A000001"

  - `data.vehicle.groupId` (string)
    Example: "c3d4e5f6-a7b8-9012-cdef-123456789012"

  - `data.vehicle.groupAppId` (number)
    Example: 12345

  - `data.vehicle.groupName` (string)
    Example: "North Division"

  - `data.eventRecorderTimezone` (string)
    Event recording device timezone when device is first configured.
    Example: "PST"

## Response 400 fields (application/json):

  - `error` (string)

  - `message` (string)