Query parameters and available metrics
When sending requests to the BI Analytics API, you specify query parameters to define what data to retrieve and how it should be returned.
In addition to the query parameters, you must specify the metrics to include in the response. Metrics determine which values are returned by the API, such as distance traveled, fuel consumption, trip count, or Eco Driving events.
Query parameters
Query parameters define the data source, how the data is grouped, and any additional filtering options for the request.
source
The source field defines which data the query should use.
Available values:
-
vehicle — vehicle data
-
driver — driver data
group_by
The group_by field defines how the result is grouped.
|
Value
|
What it shows
|
Example response structure
|
|
total
|
Total for all vehicles or drivers for the selected period
|
{ "metric": 123 }
|
|
day
|
Total for all vehicles or drivers for each day
|
{ "20260301": { "metric": 123 } }
|
|
rating
|
Each source, total for the selected period
|
{ source_id: { "metric": 123 } }
|
|
source_day
|
Each source, each day
|
{ source_id: { "20260301": { "metric": 123 } } }
|
ACCOUNT_ID
The ACCOUNT_ID parameter allows you to limit the data export to a single account.
If the query uses the partner account login and password without ACCOUNT_ID, the system will export all vehicles across all accounts available to that partner.
If you specify ACCOUNT_ID in the query, only the objects from the selected account will be loaded.
Metrics define which values are returned by the API. Specify them as a list in the metrics parameter.
For example:
metrics = [
"veh_driving_dist",
"veh_fuel_cons",
"average_speed"
]
|
The following sections describe all supported metrics.
Vehicle — general
|
Parameter
|
Description
|
|
veh_trips_cnt
|
Number of trips
|
|
veh_driving_dist
|
Mileage (km)
|
|
veh_driving_time
|
Driving time
|
|
veh_parking_time
|
Parking time
|
|
veh_ignition_time
|
Ignition on time
|
|
veh_idle_time
|
Idle time
|
|
veh_motor_hours
|
Engine hours
|
Vehicle — fuel
|
Parameter
|
Description
|
|
veh_fuel_cons
|
Fuel consumption
|
|
veh_fuel_filled
|
Fuel filled
|
|
veh_fuel_drained
|
Fuel drained
|
Vehicle — violations
|
Parameter
|
Description
|
|
veh_eco_fine
|
Eco-driving fine
|
|
veh_eco_cnt
|
Number of eco-driving violations
|
|
veh_acc_fine
|
Harsh acceleration fine
|
|
veh_acc_cnt
|
Number of harsh accelerations
|
|
veh_braking_fine
|
Harsh braking fine
|
|
veh_braking_cnt
|
Number of harsh braking events
|
|
veh_turn_fine
|
Harsh turn fine
|
|
veh_turn_cnt
|
Number of harsh turns
|
|
veh_speed_fine
|
Speeding fine
|
|
veh_speed_cnt
|
Number of speeding events
|
|
veh_belt_fine
|
Seat belt violation fine
|
|
veh_belt_cnt
|
Number of seat belt violations
|
|
veh_idle_fine
|
Idle fine
|
|
veh_idle_cnt
|
Number of idle violations
|
Vehicle — costs
|
Parameter
|
Description
|
|
veh_fuel_cost_per_kilometer
|
Fuel cost per km
|
|
veh_service_cost_per_kilometer
|
Service cost per km
|
|
veh_amount_exp
|
Total expenses
|
|
cost_of_using
|
Cost of use
|
|
average_speed
|
Average speed
|
|
veh_cars_counter
|
Number of vehicles
|
Drivers
|
Parameter
|
Description
|
|
drv_trips_cnt
|
Number of trips
|
|
drv_driving_dist
|
Mileage (km)
|
|
drv_driving_time
|
Driving time
|
|
drv_parking_time
|
Parking time
|
|
drv_fuel_cons
|
Fuel consumption
|
|
drv_fuel_filled
|
Fuel filled
|
|
drv_fuel_drained
|
Fuel drained
|
|
drv_eco_fine
|
Eco-driving fine
|
|
drv_eco_cnt
|
Number of eco-driving violations
|
|
drv_acc_fine
|
Harsh acceleration fine
|
|
drv_acc_cnt
|
Number of harsh accelerations
|
|
drv_braking_fine
|
Harsh braking fine
|
|
drv_braking_cnt
|
Number of harsh braking events
|
|
drv_turn_fine
|
Harsh turn fine
|
|
drv_turn_cnt
|
Number of harsh turns
|
|
drv_speed_fine
|
Speeding fine
|
|
drv_speed_cnt
|
Number of speeding events
|
|
drv_belt_fine
|
Seat belt violation fine
|
|
drv_belt_cnt
|
Number of seat belt violations
|
Metrics for specific Eco Driving event types
To retrieve data for specific Eco Driving event types, use metrics in the following format:
-
eco_{N}_fine— Fine points for the specified event type.
-
eco_{N}_cnt— Number of recorded events of the specified type.
N represents the unique identifier (ID) of a driving event type.
Each driving event type is automatically assigned a unique ID when it is created. The API uses this ID to generate the corresponding metric names.
For example, the predefined driving event types may have the following IDs:
|
ID
|
Event type
|
|
1
|
Acceleration
|
|
2
|
Braking
|
|
3
|
Turn
|
|
4
|
Speed
|
|
5
|
Seat Belt
|
Custom driving event types are also assigned unique IDs automatically.
When building a request, replace N with the ID of the required event type.
Examples
|
Metric
|
Returns
|
|
eco_1_fine / eco_1_cnt
|
Fine points and event count for Acceleration
|
|
eco_2_fine / eco_2_cnt
|
Fine points and event count for Braking
|
|
eco_4_fine / eco_4_cnt
|
Fine points and event count for Speed
|
|
eco_5_fine / eco_5_cnt
|
Fine points and event count for Seat Belt
|
You can find event type IDs in the driving event types directory. The ID is displayed in the ID column. When you create a new event type, the system automatically assigns it a unique ID, which can then be used in BI Analytics API metrics.
|