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.

Fleet

get

/v2/fleet/equipments/snapshot

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

Authorizations

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

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:05.796Z",
          "percent": 88.24
        },
        "DEFRemainingRatio": {
          "date": "2026-08-11T15:12:05.796Z",
          "percent": 58.24
        },
        "cumulativeIdleHours": {
          "date": "2026-08-11T15:12:05.796Z",
          "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.

Equipment

get

/v2/fleet/equipments/{id}/snapshot

Returns the last information available for all data kinds for specific equipment

Authorizations

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

Responses

200

Latest snapshot of the machine

application/json

Snapshot of the specified device for all kinds

401

Unable to authenticate the token

application/json

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

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",
    "lastPosition": {
      "date": "2019-11-06T00:00:00Z",
      "latitude": 48.858269,
      "longitude": 2.29447
    },
    "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-08-11T15:12:05.796Z",
      "percent": 88.24
    },
    "DEFRemainingRatio": {
      "date": "2026-08-11T15:12:05.796Z",
      "percent": 58.24
    },
    "cumulativeIdleHours": {
      "date": "2026-08-11T15:12:05.796Z",
      "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-08-11T15:12:05.796Z",
      "percent": 76.5
    },
    "evBatteryTemperature": {
      "date": "2026-08-11T15:12:05.796Z",
      "celsius": 35.2
    },
    "evBatteryHealth": {
      "date": "2026-08-11T15:12:05.796Z",
      "percent": 92.3
    },
    "evBatteryVoltage": {
      "date": "2026-08-11T15:12:05.796Z",
      "volts": 400.5
    },
    "evBatteryChargingState": {
      "date": "2026-08-11T15:12:05.796Z",
      "state": "charging",
      "chargingMode": "ac"
    },
    "evBatteryCurrent": {
      "date": "2026-08-11T15:12:05.796Z",
      "amperes": 150
    },
    "evChargingRate": {
      "date": "2026-08-11T15:12:05.796Z",
      "watts": 7400
    },
    "evDischargingRate": {
      "date": "2026-08-11T15:12:05.796Z",
      "watts": 3200
    },
    "evBatteryChargeCyclesCount": {
      "date": "2026-08-11T15:12:05.796Z",
      "count": 250
    },
    "evEnergyUsed": {
      "date": "2026-08-11T15:12:05.796Z",
      "wattHours": 45000
    },
    "evEnergyCharged": {
      "date": "2026-08-11T15:12:05.796Z",
      "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.

Data kind history

get

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

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

Authorizations

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}

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:05.796Z"
      }
    ],
    "id": 1,
    "serialNumber": "YVR001988",
    "since": "2019-11-06T00:00:00Z",
    "until": "2019-11-20T23:59:59Z"
  }
}

Time window strategies:

Recent data collection:

Window: Last 24-48 hours
Frequency: Every 6-8 hours
Purpose: Capture recent operational data

Weekly catch-up collection:

Window: Last 10 days
Frequency: Weekly (e.g., Sunday nights)
Purpose: Capture delayed data and ensure completeness

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.

Daily history

get

/v2/fleet/equipments/{id}/history

Returns comprehensive daily history for a piece of equipment including positions, usage, and fault codes.

Authorizations

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

Query parameters

sincestring · date-timeOptional

Default is beginning of yesterday UTC

untilstring · date-timeOptional

Default is end of today UTC

Responses

200

Specific equipment details with its history

application/json

401

Unable to authenticate the token

application/json

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

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",
    "positions": {
      "total": 1,
      "rows": [
        {
          "latitude": 48.858269,
          "longitude": 2.29447,
          "date": "2026-08-11T15:12:05.796Z"
        }
      ]
    },
    "faultCodes": {
      "total": 1,
      "rows": [
        {
          "levelLabel": "unknown",
          "severity": -1,
          "identifier": "text",
          "description": "text",
          "date": "2026-08-11T15:12:05.796Z"
        }
      ]
    },
    "fuelRemainings": {
      "total": 1,
      "rows": [
        {
          "percent": 88.24,
          "date": "2026-08-11T15:12:05.796Z"
        }
      ]
    },
    "engineConditions": {
      "total": 1,
      "rows": [
        {
          "running": true,
          "date": "2026-08-11T15:12:05.796Z"
        }
      ]
    },
    "dailyUsages": {
      "total": 1,
      "rows": [
        {
          "date": "2026-08-11T15:12:05.796Z",
          "operatingHours": {
            "hour": 8.3
          },
          "idleHours": {
            "hour": 1.5
          },
          "workingHours": {
            "hour": 6.8
          },
          "fuelUsed": {
            "fuelUsed": 99.7,
            "unit": "L"
          },
          "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"
          }
        }
      ]
    }
  }
}

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

PreviousWorking with Mixed Fleet Data NextSynchronizing with a Data Lake

Last updated 1 year ago

Was this helpful?