Exporting cumulative data to your systems

Cumulative counters are essential metrics that track equipment usage over time, providing critical data for maintenance scheduling, cost accounting, and operational analytics. This guide covers the unique challenges and best practices for working with Hiboo's cumulative counter data.

Overview

Cumulative counters differ from other equipment data because they represent running totals that continuously increase throughout an equipment's operational life. Understanding their behavior and implementing proper handling is crucial for reliable business system integration.

How Hiboo Simplifies Counter Management:

• Standardized counters: All cumulative data available in consistent formats across equipment brands

• Business-ready values: Formatted for direct consumption by enterprise systems

Unique Counter Characteristics:

• Always increasing: Values should only grow over time (except during resets)

• Reset scenarios: Counters may reset to zero during maintenance or component replacement

• Threshold significance: Specific counter values trigger business processes

Understanding Counter Types

Operating Time Counters

Cumulative operating hours track total engine runtime and are fundamental for:

• Depreciation calculations: Asset value reduction based on usage

• Maintenance scheduling: Service intervals triggered by hour thresholds

• Rental billing: Usage-based charging for rental equipment

• Efficiency analysis: Comparing operational vs idle time

Fleet

get

https://api.hiboo.iohttps://api-sandbox.hiboo.io

/v2/fleet/equipments/snapshot

Returns the last information available for all data kinds for the fleet. This endpoint is paginated.

Authorizations

JWT

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Query parameters

limitinteger · int32 · max: 50Optional

The numbers of items to return

Default: 20

offsetinteger · int32Optional

The number of items to skip before starting to collect the result set

Default: 0

searchstringOptional

Optional - if provided it will return the equipment with a fleet number or serialNumber matching the parameter

filterByInProgressSharingintegerOptional

This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.

Example: {"value":0,"summary":"Filter by not in progress sharing"}

Responses

200

Snapshot of all devices

application/json

401

Unable to authenticate the token

application/json

get/v2/fleet/equipments/snapshot

HTTPcURLJavaScriptPython

GET /v2/fleet/equipments/snapshot HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*

{
  "data": {
    "total": 1,
    "rows": [
      {
        "id": 1,
        "name": "D8000-1",
        "make": "Caterpillar",
        "model": "8000",
        "serialNumber": "YVR001988",
        "cumulativeDistance": {
          "date": "2019-11-06T00:00:00Z",
          "odometer": 54.2
        },
        "cumulativeFuelUsed": {
          "date": "2019-11-06T00:00:00Z",
          "fuelUsed": 9520.5
        },
        "fuelRemaining": {
          "date": "2019-11-06T00:00:00Z",
          "percent": 65.5
        },
        "cumulativeOperatingHours": {
          "date": "2019-11-06T00:00:00Z",
          "hour": 1.5,
          "usageHours": 1.5
        },
        "lastPosition": {
          "date": "2019-11-06T00:00:00Z",
          "latitude": 48.858269,
          "longitude": 2.29447
        },
        "cumulativeLoadCount": {
          "count": 1,
          "date": "2019-11-06T00:00:00Z"
        },
        "cumulativePayloadTotal": {
          "date": "2019-11-06T00:00:00Z",
          "payload": 1
        },
        "cumulativeActiveRegenerationHours": {
          "date": "2019-11-06T00:00:00Z",
          "hours": 15
        },
        "cumulativePowerTakeOffHours": {
          "date": "2019-11-06T00:00:00Z",
          "hours": 12
        },
        "peakDailySpeed": {
          "date": "2019-11-06T00:00:00Z",
          "speed": 100.5
        },
        "averageDailyEngineLoadFactor": {
          "date": "2026-08-11T15:12:02.933Z",
          "percent": 88.24
        },
        "DEFRemainingRatio": {
          "date": "2026-08-11T15:12:02.933Z",
          "percent": 58.24
        },
        "cumulativeIdleHours": {
          "date": "2026-08-11T15:12:02.933Z",
          "hours": 12
        }
      }
    ]
  }
}

Counter Reset Scenarios

Understanding Counter Resets

Problem: Equipment counters reset to zero during maintenance, component replacement, or system failures, disrupting business processes that depend on continuously increasing values.

Solution: Implement robust reset detection and handling strategies to maintain data continuity for business systems.

Common reset triggers:

• Scheduled maintenance: Engine overhauls or major component replacement

• Component failure: ECU replacement or system malfunctions

• Software updates: Firmware updates that clear stored counters

• Battery disconnection: Power loss that resets electronic systems

Reset detection methods:

Value decrease detection:

1. Compare current value with previous reading
2. Identify significant decreases (potential resets)
3. Validate against maintenance records
4. Apply appropriate business system update strategy

Maintenance correlation:

1. Cross-reference reset events with maintenance schedules
2. Document reset reason codes for audit trails
3. Maintain continuous usage tracking despite resets
4. Preserve historical data integrity

Business Impact Management

Problem: Counter resets can disrupt automated billing, maintenance scheduling, and depreciation calculations.

Solution: Implement business logic that maintains operational continuity despite counter resets.

Continuity strategies:

• Virtual counters: Maintain separate running totals that account for resets

• Reset adjustment: Add reset values to subsequent readings

• Parallel tracking: Use multiple data sources to validate counter accuracy

• Business rules: Define how different systems should handle reset scenarios

Example reset handling:

Equipment ABC123 counter reset detected:
- Previous reading: 1,247.5 hours
- Current reading: 0.0 hours (reset to zero)
- Business system action: Add 1,247.5 to all future readings
- Maintenance record: Updated with reset event and reason

Threshold-Based Triggers

Maintenance Scheduling

Problem: Business systems need to trigger maintenance actions when equipment counters reach specific thresholds.

Solution: Implement threshold monitoring that accounts for counter behavior and business requirements.

Data kind history

get

https://api.hiboo.iohttps://api-sandbox.hiboo.io

/v2/fleet/equipments/{id}/{dataKind}

Returns time series data for a specific data kind for a piece of equipment.

Authorizations

JWT

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Path parameters

idinteger · int32Required

ID of the equipment

dataKindstring · enumRequired

Data kind identifier.

Example: batteryLevelPossible values:

Query parameters

sincestring · date-timeOptional

Default is beginning of yesterday UTC

untilstring · date-timeOptional

Default is end of today UTC

Responses

200

Snapshot of all devices

application/json

401

Unable to authenticate the token

application/json

get/v2/fleet/equipments/{id}/{dataKind}

HTTPcURLJavaScriptPython

GET /v2/fleet/equipments/{id}/{dataKind} HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*

{
  "data": {
    "total": 1,
    "rows": [
      {
        "percent": 88.24,
        "date": "2026-08-11T15:12:02.933Z"
      }
    ],
    "id": 1,
    "serialNumber": "YVR001988",
    "since": "2019-11-06T00:00:00Z",
    "until": "2019-11-20T23:59:59Z"
  }
}

Threshold implementation:

Service interval triggers:

Operating hours: Trigger maintenance at 250, 500, 1000 hour intervals
Distance milestones: Service alerts at 5,000, 10,000 km intervals
Load cycles: Component inspection after 10,000 cycles
Specialized systems: PTO hours for auxiliary equipment maintenance

Business system integration:

1. Monitor counter progression in real-time
2. Calculate time/usage until next threshold
3. Generate advance warnings for maintenance planning
4. Trigger work orders when thresholds are reached
5. Update maintenance schedules after service completion

Usage-Based Billing

Problem: Rental and service agreements require accurate usage tracking for billing purposes.

Solution: Implement precise counter monitoring with appropriate validation and billing integration.

Billing counter applications:

• Rental equipment: Hourly charges based on operating time

• Service contracts: Usage-based maintenance pricing

• Project allocation: Equipment costs distributed by usage

• Performance contracts: Billing based on productivity metrics

Billing integration considerations:

Reading frequency: Align with billing periods (daily, weekly, monthly)
Validation rules: Ensure counter progression is reasonable
Reset handling: Maintain billing continuity despite counter resets
Audit trails: Document all counter readings for billing disputes