> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectedfleet.michelin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vehicle Utilisation Hours
> Returns summary utilisation information for a vehicle for all journeys where the journey started in the period.
The end date of the journey does not have to be within the period. If the vehicle has been configured for a PTO, then driving and idling time with PTO active and with PTO inactive are included in the response. Details for private journeys that started in the period are included in the utilisation values.
If vehicleId or groupId is not specified, then details for all vehicles are returned. If groupId is specified, then the utilisation for all vehicles in the specified group are included in the output. Either vehicleId or groupId can be specified as an input parameter, an error is returned if both are specified.
## OpenAPI
````yaml /api-reference/performance.json get /public/v1/customer/{customerId}/utilisation/vehicle
openapi: 3.0.1
info:
title: Performance
description: >-
Delivers deeper insights into driver behaviour, fuel efficiency, CO₂ impact
and safe driving practices.
contact:
name: Masternaut
url: https://www.masternaut.com
email: support@masternautconnect.com
version: 124.0.2607160821
servers:
- url: https://api.masternautconnect.com/connect-webservices/services
description: Product Server
security:
- basicAuth: []
tags:
- name: /alert
description: Alert history and notification management operations
- name: /driver
description: Driver Operations
- name: /driverbehaviourmetrics
description: Driver Behaviour Metrics
- name: customers
description: Customer Behaviour Metrics
- name: /ecoscore
description: EcoScore
- name: /fuel
description: Fuel
- name: /idling
description: Idling
- name: /speeding
description: Speeding
- name: /tokenInformation
description: Token operations
- name: /utilisation
description: Utilisation
- name: /vehicle
description: Vehicle management operations
paths:
/public/v1/customer/{customerId}/utilisation/vehicle:
get:
tags:
- /utilisation
summary: Vehicle Utilisation Hours
description: >-
Returns summary utilisation information for a vehicle for all journeys
where the journey started in the period.
The end date of the
journey does not have to be within the period. If the vehicle has been
configured for a PTO, then driving and idling time with PTO active and
with PTO inactive are included in the response. Details for private
journeys that started in the period are included in the utilisation
values.
If vehicleId or groupId is not specified, then details
for all vehicles are returned. If groupId is specified, then the
utilisation for all vehicles in the specified group are included in the
output. Either vehicleId or groupId can be specified as an input
parameter, an error is returned if both are specified.
operationId: getVehicleUtilisation
parameters:
- name: customerId
in: path
required: true
schema:
type: string
- name: startDate
in: query
description: >-
Start date and time for the utilisation period in UTC format
(yyyy-MM-dd'T'HH:mm:ss)
required: true
schema:
type: string
description: >-
Start date and time for the utilisation period in UTC format
(yyyy-MM-dd'T'HH:mm:ss)
format: date-time
- name: endDate
in: query
description: >-
End date and time for the utilisation period in UTC format
(yyyy-MM-dd'T'HH:mm:ss)
required: true
schema:
type: string
description: >-
End date and time for the utilisation period in UTC format
(yyyy-MM-dd'T'HH:mm:ss)
format: date-time
- name: vehicleId
in: query
description: >-
Unique identifier of the vehicle to retrieve utilisation data for.
Must not be used together with groupId
required: false
schema:
type: string
description: >-
Unique identifier of the vehicle to retrieve utilisation data for.
Must not be used together with groupId
example: vehicle-id
example: vehicle-id
- name: groupId
in: query
description: >-
Unique identifier of the group to retrieve utilisation data for all
vehicles in the group. Must not be used together with vehicleId
required: false
schema:
type: string
description: >-
Unique identifier of the group to retrieve utilisation data for
all vehicles in the group. Must not be used together with
vehicleId
example: group-id
example: group-id
responses:
'200':
description: Vehicle utilisation data successfully returned
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/UtilisationVehicleResultDto'
'400':
description: >-
When both vehicleId and groupId are specified, or when filtering
field contains id of resource which is not visible to user
content:
application/json;charset=UTF-8:
schema:
$ref: '#/components/schemas/ApiErrorDto'
'404':
description: No utilisation data found for the specified criteria
components:
schemas:
UtilisationVehicleResultDto:
type: object
properties:
utilisations:
type: array
description: >-
List of individual vehicle utilisation records with detailed hours
and activity data
items:
$ref: '#/components/schemas/UtilisationVehicleDto'
averageStartTime:
type: string
description: >-
Calculated average start time across all vehicle utilisations in
HH:mm format
averageEndTime:
type: string
description: >-
Calculated average end time across all vehicle utilisations in HH:mm
format
description: >-
Response containing vehicle utilisation hours data including individual
utilisation records and calculated average start/end times
ApiErrorDto:
type: object
properties:
errorCode:
type: integer
format: int32
errorMessage:
type: string
offendingFields:
type: array
items:
type: string
UtilisationVehicleDto:
type: object
properties:
assetId:
type: string
description: Unique identifier of the vehicle
assetRegistration:
type: string
description: Vehicle registration number
assetName:
type: string
description: Friendly name of the vehicle
groupName:
type: string
description: Name of the group the vehicle belongs to
utilisation:
type: array
description: >-
List of utilisation periods for the vehicle with detailed hours and
activity data
items:
$ref: '#/components/schemas/UtilisationDto'
averageStartTime:
type: string
description: Calculated average start time for the vehicle in HH:mm format
averageEndTime:
type: string
description: Calculated average end time for the vehicle in HH:mm format
description: >-
Individual vehicle utilisation record containing vehicle details and
list of utilisation periods
UtilisationDto:
type: object
properties:
firstStart:
type: string
description: >-
Date and time of the first journey start (ignition on), in UTC, in
format of YYYY-MM-DDThh:mm:ss.
format: date-time
lastStop:
type: string
description: >-
Date and time of the last journey end (ignition off), in UTC, in
format of YYYY-MM-DDThh:mm:ss.
format: date-time
totalTime:
type: integer
description: Sum of (driveTime + IdleTime + idleTimeWithPto) (in seconds).
format: int64
driveTime:
type: integer
description: Sum of (driveTimeWithPto + driveTimeWithoutPto) (in seconds).
format: int64
driveTimeWithPto:
type: integer
description: Total time driving with PTO active (in seconds).
format: int64
driveTimeWithoutPto:
type: integer
description: Total time driving with PTO inactive (in seconds).
format: int64
idleTime:
type: integer
description: Total time idling with PTO inactive (in seconds).
format: int64
idleTimeWithPto:
type: integer
description: Total time idling with PTO active (in seconds).
format: int64
stopTime:
type: integer
description: Total time stopped (in seconds).
format: int64
countOfStopTime:
type: integer
description: Number of stops for all journeys.
format: int32
description: >-
Detailed utilisation period data containing timestamps and various time
measurements for vehicle/driver activity analysis
securitySchemes:
basicAuth:
type: http
scheme: basic
````