Setting up efficient polling strategies
Understanding when and how often to poll Hiboo's API ensures you get the data you need while maintaining system efficiency. This guide covers the essential polling patterns for different business scenarios.
Overview
Hiboo processes equipment data in near real-time as it's received from various data sources, but transmission patterns vary significantly across equipment brands and operational scenarios.
Key Data Characteristics:
Near real-time processing: Data is computed immediately when received by Hiboo
Variable transmission timing: Equipment sends data based on events or fixed schedules, depending on the source
Delayed data scenarios: Some data only transmits when specific conditions are met
Common Delay Examples:
Engine-off reporting: Some brands only report "Engine off" events when the engine restarts
Weekend gaps: Reduced connectivity and activity during weekends
Connectivity issues: Remote locations may have intermittent data transmission
Recommended Baseline Strategy:
Frequent monitoring: Multiple polls per day/hour for operational data
Weekly catch-up: 10-day data windows to capture delayed transmissions
Real-Time Fleet Monitoring
Current Fleet Activity
Problem: You need current operational information for your entire fleet to support operational decisions and monitoring dashboards.
Solution: Use snapshot endpoints for immediate equipment status across your fleet.
Returns the last information available for all data kinds for the fleet. This endpoint is paginated.
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
The numbers of items to return
20The number of items to skip before starting to collect the result set
0Optional - if provided it will return the equipment with a fleet number or serialNumber matching the parameter
This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.
{"value":0,"summary":"Filter by not in progress sharing"}Snapshot of all devices
Unable to authenticate the token
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",
"pin": "12345678901234567",
"vin": "1HGBH41JXMN109186",
"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,
"altitude": 35,
"speed": 25.5,
"heading": 125.3,
"postalAddress": "5 Avenue Anatole France, 75007 Paris, France"
},
"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-01-01T00:00:00.000Z",
"percent": 88.24
},
"DEFRemainingRatio": {
"date": "2026-01-01T00:00:00.000Z",
"percent": 58.24
},
"cumulativeIdleHours": {
"date": "2026-01-01T00:00:00.000Z",
"hours": 12
}
}
]
}
}Recommended polling frequency:
Operational hours: Every 15-30 minutes (6 AM - 6 PM)
Off-hours: Every 60 minutes
Weekends: Every 2-4 hours (unless 24/7 operations)
Individual Equipment Monitoring
Problem: You need detailed current activity for specific high-value or critical equipment pieces.
Solution: Poll individual equipment snapshots for focused monitoring.
Returns the last information available for all data kinds for specific equipment
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
ID of the equipment
Latest snapshot of the machine
Snapshot of the specified device for all kinds
Unable to authenticate the token
GET /v2/fleet/equipments/{id}/snapshot HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*
{
"data": {
"id": 1,
"name": "CAT - 5",
"make": "Caterpillar",
"model": "816K",
"serialNumber": "XICWITIDLXSX",
"pin": "12345678901234567",
"vin": "1HGBH41JXMN109186",
"lastPosition": {
"date": "2019-11-06T00:00:00Z",
"latitude": 48.858269,
"longitude": 2.29447,
"altitude": 35,
"speed": 25.5,
"heading": 125.3,
"postalAddress": "5 Avenue Anatole France, 75007 Paris, France"
},
"cumulativeOperatingHours": {
"date": "2019-11-06T00:00:00Z",
"hour": 1.5
},
"cumulativeDistance": {
"date": "2019-11-06T00:00:00Z",
"odometer": 54.2,
"unit": "km"
},
"cumulativeFuelUsed": {
"date": "2019-11-06T00:00:00Z",
"fuelUsed": 9520.5,
"unit": "L"
},
"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-01-01T00:00:00.000Z",
"percent": 88.24
},
"DEFRemainingRatio": {
"date": "2026-01-01T00:00:00.000Z",
"percent": 58.24
},
"cumulativeIdleHours": {
"date": "2026-01-01T00:00:00.000Z",
"hours": 12
},
"fuelRemaining": {
"date": "2019-11-06T00:00:00Z",
"percent": 65.5
},
"engineCondition": {
"date": "2019-11-06T00:00:00Z",
"running": true
},
"nextMaintenance": {
"date": "2019-11-06T00:00:00Z",
"nextMaintenanceDate": "2019-11-06T00:00:00Z",
"usageHoursUntilNextMaintenance": 505,
"kmUntilNextMaintenance": 1250
},
"evBatteryLevel": {
"date": "2026-01-01T00:00:00.000Z",
"percent": 76.5
},
"evBatteryTemperature": {
"date": "2026-01-01T00:00:00.000Z",
"celsius": 35.2
},
"evBatteryHealth": {
"date": "2026-01-01T00:00:00.000Z",
"percent": 92.3
},
"evBatteryVoltage": {
"date": "2026-01-01T00:00:00.000Z",
"volts": 400.5
},
"evBatteryChargingState": {
"date": "2026-01-01T00:00:00.000Z",
"state": "charging",
"chargingMode": "ac"
},
"evBatteryCurrent": {
"date": "2026-01-01T00:00:00.000Z",
"amperes": 150
},
"evChargingRate": {
"date": "2026-01-01T00:00:00.000Z",
"watts": 7400
},
"evDischargingRate": {
"date": "2026-01-01T00:00:00.000Z",
"watts": 3200
},
"evBatteryChargeCyclesCount": {
"date": "2026-01-01T00:00:00.000Z",
"count": 250
},
"evEnergyUsed": {
"date": "2026-01-01T00:00:00.000Z",
"wattHours": 45000
},
"evEnergyCharged": {
"date": "2026-01-01T00:00:00.000Z",
"wattHours": 50000
}
}
}Use this approach when:
Critical equipment: High-value assets requiring constant monitoring
Active projects: Equipment currently deployed on important jobs
Performance tracking: Detailed monitoring of specific equipment performance
Recommended polling patterns:
Critical equipment: Every 5-15 minutes during active use
Standard monitoring: Every 30 minutes during operational hours
Historical Data Collection
Comprehensive Equipment Data History
Problem: You need comprehensive historical data for analysis, reporting, and compliance requirements.
Solution: Use time series endpoints with strategic time windows to capture complete data sets.
Returns time series data for a specific data kind for a piece of equipment.
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
ID of the equipment
Data kind identifier.
batteryLevelPossible values: Default is beginning of yesterday UTC
Default is end of today UTC
Snapshot of all devices. The shape of each row varies by data kind — this example shows fuelRemaining. For dailyFuel and dailyCO2, rows also include an estimated boolean: whether the value was estimated from usage hours × the model's consumption rate, rather than measured from telematics.
Unable to authenticate the token
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-01-01T00:00:00.000Z"
}
],
"id": 1,
"serialNumber": "YVR001988",
"since": "2019-11-06T00:00:00Z",
"until": "2019-11-20T23:59:59Z"
}
}Time window strategies:
Recent data collection:
Weekly catch-up collection:
Simplified Equipment History
Problem: You need one endpoint for historical data including positions, fault codes, daily usage patterns, and operational metrics for comprehensive analysis.
Solution: Use equipment history endpoints for consolidated historical data across multiple data types.
Returns comprehensive daily history for a piece of equipment including positions, usage, and fault codes.
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
ID of the equipment
Default is beginning of yesterday UTC
Default is end of today UTC
Specific equipment details with its history
Unable to authenticate the token
GET /v2/fleet/equipments/{id}/history HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*
{
"data": {
"id": 1,
"name": "D8000-1",
"make": "Caterpillar",
"model": "8000",
"serialNumber": "YVR001988",
"pin": "12345678901234567",
"vin": "1HGBH41JXMN109186",
"positions": {
"total": 1,
"rows": [
{
"latitude": 48.858269,
"longitude": 2.29447,
"date": "2026-01-01T00:00:00.000Z",
"altitude": 35,
"speed": 25.5,
"heading": 125.3,
"postalAddress": "5 Avenue Anatole France, 75007 Paris, France"
}
]
},
"faultCodes": {
"total": 1,
"rows": [
{
"levelLabel": "unknown",
"severity": -1,
"identifier": "text",
"description": "text",
"date": "2026-01-01T00:00:00.000Z"
}
]
},
"fuelRemainings": {
"total": 1,
"rows": [
{
"percent": 88.24,
"date": "2026-01-01T00:00:00.000Z"
}
]
},
"engineConditions": {
"total": 1,
"rows": [
{
"running": true,
"date": "2026-01-01T00:00:00.000Z"
}
]
},
"dailyUsages": {
"total": 1,
"rows": [
{
"date": "2026-01-01T00:00:00.000Z",
"operatingHours": {
"hour": 8.3
},
"idleHours": {
"hour": 1.5
},
"workingHours": {
"hour": 6.8
},
"fuelUsed": {
"fuelUsed": 99.7,
"unit": "L",
"estimated": false
},
"dailyDistance": {
"odometer": 54.2,
"unit": "km"
},
"cumulativeIdleHours": {
"hour": 1064.6
},
"cumulativeOperatingHours": {
"hour": 1064.6
},
"cumulativeFuelUsed": {
"fuelUsed": 9520.5,
"unit": "L"
},
"cumulativeDistance": {
"odometer": 5423.9,
"unit": "km"
},
"cumulativeLoadCount": {
"count": 13569
},
"cumulativePayloadTotal": {
"payload": 447839.9,
"payloadUnit": "tonnes"
},
"cumulativeActiveRegenerationHours": {
"hour": 10.92
},
"cumulativePowerTakeOffHours": {
"hour": 31.21
},
"peakDailySpeed": {
"speed": 14.91,
"speedUnit": "km/h"
},
"averageDailyEngineLoadFactor": {
"percent": 35.9
},
"DEFRemainingRatio": {
"percent": 62,
"tankCapacity": 41,
"tankCapacityUnit": "L"
},
"co2": {
"weight": 123,
"unit": "kg",
"estimated": false
}
}
]
}
}
}What this endpoint provides:
Position history: Equipment locations over time
Fault codes: Diagnostic events and equipment issues
Fuel data: Remaining fuel levels and consumption patterns
Engine conditions: Running/idle status history
Daily usage summaries: Operating hours, idle time, working hours, distances
Cumulative metrics: Total hours, fuel consumption, distance, load counts, payload
Performance data: Speed patterns, load factors, emissions (CO2), DEF levels
Use this endpoint when:
Comprehensive reporting: You need multiple data types in a single request
Dashboard overviews: Consolidated view of equipment performance
Historical analysis: Studying patterns across different operational metrics
Strategic polling approach:
Daily collection: Previous day's data every morning (captures overnight transmissions)
Weekly collection: Previous week's data every Monday (catches weekend delays)
Note: For specific data types with higher frequency or detailed time-series analysis, use the /{dataKind} endpoint described above.
Best Practices
Polling Frequency Guidelines
High-frequency (every 5-15 minutes):
Critical equipment monitoring
Real-time dashboard updates
Active project tracking
Medium-frequency (every 30 minutes - 2 hours):
Standard fleet monitoring
Performance tracking
Operational oversight
Low-frequency (daily/weekly):
Historical data collection
Compliance reporting
Long-term analysis
Time Window Strategy
Recent data (last 24-48 hours):
Operational monitoring
Real-time decision making
Current status tracking
Catch-up data (last 7-10 days):
Complete data collection
Weekend/holiday coverage
Data quality assurance
Implementation Tips
Error handling:
Implement retry logic for temporary failures
Track last successful poll timestamps
Use overlapping time windows to ensure completeness
Performance optimization:
Use appropriate pagination for large fleets
Cache recent data to reduce redundant requests
Schedule bulk operations during low-activity periods
Monitoring:
Track polling success rates and response times
Alert on extended periods without successful data collection
Regular review of polling strategies against business needs
Last updated
Was this helpful?