> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Latest Vehicle Locations

> List the latest location of the vehicles in the connected account.

This endpoint will call the provider's API in real time to get the latest location of the vehicle.
*Please note: this endpoint will exclude vehicles that have no last known location.*


## OpenAPI

````yaml GET /vehicles/locations
openapi: 3.1.0
info:
  title: Terminal Telematics API
  description: >-
    Terminal is a unified API that makes it easy to integrate with the leading
    telematics service providers.
  version: '0.0'
  contact:
    name: Terminal
    email: connect@withterminal.com
    url: https://www.withterminal.com
servers:
  - url: https://api.withterminal.com/tsp/v1
    description: Production
  - url: https://api.sandbox.withterminal.com/tsp/v1
    description: Sandbox
security:
  - Authorization: []
tags:
  - name: Authentication
  - name: Connections
  - name: Data Management
  - name: Drivers
  - name: Groups
  - name: Hours of Service
  - name: IFTA
  - name: Issues
  - name: Link
  - name: Providers
  - name: Safety
  - name: Trailers
  - name: Vehicles
  - name: Vehicle Utilization
  - name: Webhook Events
paths:
  /vehicles/locations:
    parameters: []
    get:
      tags:
        - Vehicles
      summary: Latest Vehicle Locations
      description: >-
        List the latest location of the vehicles in the connected account.

        This endpoint will call the provider's API in real time to get the
        latest location of the vehicle. 

        _Please note: this endpoint will exclude vehicles that have no last
        known location._
      operationId: listLatestVehicleLocations
      parameters:
        - $ref: '#/components/parameters/XApplicationId'
        - $ref: '#/components/parameters/ConnectionToken'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Raw'
        - $ref: '#/components/parameters/VehicleIds'
        - $ref: '#/components/parameters/DriverIds'
        - schema:
            type: string
            enum:
              - vehicle
              - driver
              - vehicle,driver
              - driver,vehicle
          in: query
          name: expand
          description: Expand resources in the returned response
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/LatestVehicleLocation'
                  next:
                    $ref: '#/components/schemas/PaginationCursor'
                required:
                  - results
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ProviderProvisioningPendingError'
        '410':
          $ref: '#/components/responses/GoneError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplementedError'
        '502':
          $ref: '#/components/responses/BadGatewayError'
        '503':
          $ref: '#/components/responses/ProviderUnavailableError'
        '504':
          $ref: '#/components/responses/GatewayTimeoutError'
components:
  parameters:
    XApplicationId:
      name: X-Application-Id
      in: header
      required: false
      description: >-
        Scopes the request to a Terminal application in the caller's
        organization. Required for multi-application organizations when using a
        user session or OAuth access token. API keys are already bound to a
        single application.
      schema:
        type: string
    ConnectionToken:
      name: Connection-Token
      in: header
      required: true
      schema:
        type: string
        example: con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4
        pattern: ^con_tkn_\S+$
      description: >-
        The token returned when a user authenticated their account. This
        authorizes access to a specific account.
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
        format: cursor
        pattern: ^[A-Za-z0-9+/=_-]+$
        example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
      description: Pagination cursor to start requests from
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
      description: The maximum number of results to return in a page.
    Raw:
      name: raw
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        Include raw responses used to normalize model. Used for debugging or
        accessing unique properties that are not unified.
    VehicleIds:
      name: vehicleIds
      in: query
      required: false
      schema:
        type: string
        pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}(\s*,\s*vcl_[0-9A-HJKMNP-TV-Z]{26})*$
      description: >-
        Comma separated list of vehicle IDs to filter for. Can filter up to 50
        vehicles at a time. Each ID must use the `vcl_` prefix.
    DriverIds:
      name: driverIds
      in: query
      required: false
      schema:
        type: string
        pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}(\s*,\s*drv_[0-9A-HJKMNP-TV-Z]{26})*$
      description: >-
        Comma separated list of driver IDs to filter for. Can filter up to 50
        drivers at a time. Each ID must use the `drv_` prefix.
  schemas:
    LatestVehicleLocation:
      title: Latest Vehicle Location
      x-model-category: real-time
      allOf:
        - $ref: '#/components/schemas/BaseVehicleLocation'
        - type: object
          properties:
            odometer:
              $ref: '#/components/schemas/DistanceInKilometers'
            fuel:
              $ref: '#/components/schemas/FuelTanksPercentage'
            engineState:
              $ref: '#/components/schemas/EngineState'
              description: The current state of the vehicle's engine
            engineRuntime:
              $ref: '#/components/schemas/DurationInMS'
              description: Total engine runtime duration
            raw:
              $ref: '#/components/schemas/RawDataList'
      x-description: The latest record of a vehicle's location according to the provider.
    PaginationCursor:
      title: Pagination Cursor
      type: string
      example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
      description: Cursor used for pagination.
      format: cursor
      pattern: ^[A-Za-z0-9+/=_-]+$
    BaseVehicleLocation:
      title: Base Vehicle Location
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ProviderCode'
        vehicle:
          $ref: '#/components/schemas/ExpandableVehicle'
          description: The vehicle that the location is tracking.
        driver:
          $ref: '#/components/schemas/ExpandableDriver'
          description: >-
            The driver that was driving the vehicle at the time of this
            location.
        locatedAt:
          $ref: '#/components/schemas/ISODateTime'
        location:
          $ref: '#/components/schemas/Coordinates'
        address:
          type: object
          description: >-
            Reverse geocoded address details for locations when available at the
            source.
          properties:
            formatted:
              type: string
              example: 1.5 miles from Austin, TX
        heading:
          $ref: '#/components/schemas/HeadingInDegrees'
        speed:
          $ref: '#/components/schemas/SpeedInKPH'
      required:
        - provider
        - vehicle
        - locatedAt
        - location
    DistanceInKilometers:
      title: Distance In Kilometers
      type: number
      format: double
      description: Distance in kilometers
      example: 100.25
    FuelTanksPercentage:
      title: Fuel Tanks Percentage
      type: object
      description: Fuel percentage
      properties:
        primaryPercentage:
          $ref: '#/components/schemas/FuelPercentage'
          description: The percentage value of how much fuel is left in the primary tank.
        secondaryPercentage:
          $ref: '#/components/schemas/FuelPercentage'
          description: The percentage value of how much fuel is left in the secondary tank.
      required:
        - primaryPercentage
    EngineState:
      type: string
      enum:
        - 'on'
        - 'off'
        - idle
    DurationInMS:
      title: DurationInMS
      type: integer
      example: 0
      description: Duration in MS
    RawDataList:
      title: RawDataList
      type: array
      example: []
      items:
        $ref: '#/components/schemas/RawData'
    ErrorPathDetail:
      title: ErrorPathDetail
      type: object
      properties:
        message:
          type: string
          example: '''vehicleId'' property must be a valid ulid'
        path:
          type: string
          example: '{requestQuery}.vehicleId'
        suggestion:
          type: string
          example: Please ensure you submit a valid 'vehicleId' property
        context:
          type: object
      required:
        - message
        - path
    ProviderCode:
      type: string
      example: geotab
      description: >-
        Every provider has a unique code to identify it across Terminal's
        system. You can find each provider's code under [provider
        details](/providers).
    ExpandableVehicle:
      example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
      oneOf:
        - $ref: '#/components/schemas/VehicleId'
        - $ref: '#/components/schemas/ExpandedVehicle'
    ExpandableDriver:
      example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC
      oneOf:
        - $ref: '#/components/schemas/DriverId'
        - $ref: '#/components/schemas/ExpandedDriver'
    ISODateTime:
      title: ISODateTime
      type: string
      format: date-time
      example: '2021-01-06T03:24:53.000Z'
      description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date'
    Coordinates:
      title: Coordinates
      type: object
      properties:
        longitude:
          type: number
          example: -122.4194155
        latitude:
          type: number
          example: 37.7749295
      required:
        - longitude
        - latitude
    HeadingInDegrees:
      title: Heading In Degrees
      type: number
      description: Heading in degrees
      example: 25
    SpeedInKPH:
      title: Speed In KPH
      type: number
      description: Speed in KPH rounded to 2 decimal places.
      example: 95.33
    FuelPercentage:
      title: Fuel Percentage
      type: number
      example: 50
      minimum: 0
      maximum: 100
      description: The percentage value of how much fuel is left in the tank.
    RawData:
      title: RawData
      type: object
      properties:
        provider:
          type: string
        schema:
          type: string
        extractedAt:
          type: string
        data:
          type: object
      required:
        - provider
        - schema
        - extractedAt
        - data
    VehicleId:
      title: VehicleId
      description: Unique identifier for the vehicle in Terminal.
      type: string
      format: ulid
      pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}$
      example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
    ExpandedVehicle:
      title: Expanded Vehicle
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/VehicleId'
        sourceId:
          $ref: '#/components/schemas/SourceId'
        provider:
          $ref: '#/components/schemas/ProviderCode'
        status:
          type: string
          enum:
            - active
            - inactive
          example: active
          description: The status in the providers system
        vin:
          title: VIN
          type: string
          example: 1HGCM82633A004352
        name:
          type: string
          example: Big Red
        make:
          type: string
          example: Peterbilt
        model:
          type: string
          example: Model 579
        year:
          type: integer
          example: 2016
        groups:
          type: array
          description: The groups the vehicle belongs to.
          items:
            $ref: '#/components/schemas/GroupId'
        devices:
          type: array
          description: The devices installed in the vehicle.
          items:
            $ref: '#/components/schemas/DeviceId'
        licensePlate:
          type: object
          properties:
            state:
              $ref: '#/components/schemas/State'
            number:
              type: string
              example: ABC-1234
        fuelType:
          enum:
            - gasoline
            - diesel
            - propane
            - electric
            - hybrid_gasoline
            - hybrid_diesel
            - biodiesel
            - compressed_natural_gas
            - liquefied_natural_gas
            - ethanol
            - hydrogen
            - plug_in_hybrid
          example: diesel
        fuelEfficiency:
          type: number
          deprecated: true
          description: >-
            This field will be removed in the future as is not commonly
            available from providers.
          example: 27.4
        fuelTankCapacity:
          description: Maximum amount of fuel vehicle can hold in liters.
          title: Volume In Liters
          type: number
          example: 95.33
        createdAt:
          $ref: '#/components/schemas/SourceCreatedAt'
        updatedAt:
          $ref: '#/components/schemas/SourceUpdatedAt'
        metadata:
          $ref: '#/components/schemas/CoreEntityMetadata'
        raw:
          $ref: '#/components/schemas/RawDataList'
      required:
        - id
        - sourceId
        - provider
        - status
        - metadata
      x-description: The model representing a vehicle in Terminal.
    DriverId:
      title: DriverId
      description: Unique identifier for the driver in Terminal.
      type: string
      format: ulid
      pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}$
      example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC
    ExpandedDriver:
      title: Expanded Driver
      type: object
      additionalProperties: false
      examples: []
      properties:
        id:
          $ref: '#/components/schemas/DriverId'
        sourceId:
          $ref: '#/components/schemas/SourceId'
        provider:
          $ref: '#/components/schemas/ProviderCode'
        status:
          type: string
          enum:
            - active
            - inactive
          example: active
          description: The status in the providers system
        firstName:
          type: string
          example: Mike
        middleName:
          type: string
          example: Bryan
        lastName:
          type: string
          example: Miller
        email:
          type: string
          format: email
          example: driver@example.com
        phone:
          title: Phone
          type: string
          pattern: ^\+?\d{10,14}$
          example: '+19058084567'
          description: >-
            Phone number formatted in
            [E.164](https://www.twilio.com/docs/glossary/what-e164) formatting
        username:
          type: string
          description: The driver's username for login purposes
          example: driver123
        license:
          type: object
          properties:
            state:
              $ref: '#/components/schemas/State'
            number:
              type: string
              example: 123-456-789-0
        groups:
          type: array
          description: The groups the driver belongs to.
          items:
            $ref: '#/components/schemas/GroupId'
        createdAt:
          $ref: '#/components/schemas/SourceCreatedAt'
        updatedAt:
          $ref: '#/components/schemas/SourceUpdatedAt'
        metadata:
          $ref: '#/components/schemas/CoreEntityMetadata'
        raw:
          $ref: '#/components/schemas/RawDataList'
      required:
        - id
        - sourceId
        - provider
        - status
        - metadata
      x-description: The model representing a driver in Terminal.
    SourceId:
      title: SourceId
      type: string
      example: '123456789'
      description: The ID used to represent the entity in the source system.
    GroupId:
      title: GroupId
      type: string
      format: ulid
      example: group_01D8ZQFGHVJ858NBF2Q7DV9MNC
    DeviceId:
      title: DeviceId
      type: string
      format: ulid
      example: dvc_61D9ZWFGHVJ858NBF2Q7DV9MNC
    State:
      title: State
      type: string
      enum:
        - 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
      example: TN
      description: US State or Canadian Province
    SourceCreatedAt:
      title: SourceCreatedAt
      type: string
      format: date-time
      description: >-
        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.
    SourceUpdatedAt:
      title: SourceUpdatedAt
      type: string
      format: date-time
      description: >-
        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.
    CoreEntityMetadata:
      title: CoreEntityMetadata
      type: object
      description: Internal metadata about the record.
      required:
        - addedAt
        - modifiedAt
      properties:
        addedAt:
          $ref: '#/components/schemas/AddedAt'
        modifiedAt:
          $ref: '#/components/schemas/ModifiedAt'
        deletedAt:
          $ref: '#/components/schemas/DeletedAt'
        visibility:
          type: string
          enum:
            - visible
            - hidden_by_exclude_list
            - hidden_by_include_list
            - hidden_by_status
            - deleted
          example: visible
          description: >-
            Visibility status of a resource. Read more about hidden records
            [here](https://docs.withterminal.com/guides/vehicle-driver-filtering).
    AddedAt:
      title: AddedAt
      type: string
      format: date-time
      description: >-
        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:
      title: ModifiedAt
      type: string
      format: date-time
      description: >-
        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:
      title: DeletedAt
      type: string
      format: date-time
      description: >-
        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.
  responses:
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - bad_request
              message:
                type: string
                example: Invalid request body
              detail:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorPathDetail'
            required:
              - code
              - message
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - unauthorized
              message:
                type: string
                example: Unauthorized Request
              detail:
                type: string
                example: Please ensure you have a valid API key
            required:
              - code
              - message
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - forbidden
              message:
                type: string
                example: Forbidden Request
              detail:
                type: string
                example: >-
                  Please ensure the connection token matches the resource you
                  are attempting to access.
            required:
              - code
              - message
    ProviderProvisioningPendingError:
      description: Provider Provisioning Pending
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - provider_provisioning_pending
              message:
                type: string
                example: Provider credentials are still being provisioned
            required:
              - code
              - message
    GoneError:
      description: Gone
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - gone
                  - connection_deleted
                example: connection_deleted
              message:
                type: string
                example: Connection has been deleted and cannot be used
            required:
              - code
              - message
    UnprocessableEntityError:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - unprocessable_entity
                  - connection_disconnected
                  - insufficient_permissions
                  - invalid_credentials
                  - oauth_client_id_unknown
                example: connection_disconnected
              message:
                type: string
                example: Connection must be connected to perform this action
              detail:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorPathDetail'
                example: []
            required:
              - code
              - message
    TooManyRequestsError:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
            properties:
              code:
                enum:
                  - too_many_requests
              retryAfter:
                description: The number of seconds to wait before retrying the request
                type: integer
                example: 60
              message:
                type: string
                example: Too Many Requests
              detail:
                type: string
                example: You have exceeded your rate limit. Please try again later.
            required:
              - code
              - message
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - internal_server_error
              message:
                type: string
                example: Internal Server Error
              detail:
                type: string
                example: Something went wrong
            required:
              - code
              - message
    NotImplementedError:
      description: Not Implemented
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - not_implemented
              message:
                type: string
                example: Not Implemented
              detail:
                type: string
                example: This endpoint is not yet implemented
            required:
              - code
              - message
    BadGatewayError:
      description: Bad Gateway
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - bad_gateway
              message:
                type: string
                example: Provider Unavailable
              detail:
                type: string
                example: Error response received from provider with status 500
            required:
              - code
              - message
    ProviderUnavailableError:
      description: Provider Unavailable Error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - provider_unavailable
              message:
                type: string
                example: Provider is not currently available
            required:
              - code
              - message
    GatewayTimeoutError:
      description: Gateway Timeout Error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - gateway_timeout
              message:
                type: string
                example: Gateway Timeout
            required:
              - code
              - message
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.