Skip to content

get_trip_stats.md

Latest commit

 

History

History
81 lines (63 loc) · 2.98 KB

get_trip_stats.md

File metadata and controls

81 lines (63 loc) · 2.98 KB
Raw

get_trip_stats

Aggregated summary of a load's whole GPS trip, computed on demand over every recorded ping (not just the last 500): distance, duration, speed profile, hard-acceleration/braking counts, city/highway/parked/night shares and GPS coverage.

Price: $0.02 per call from the prepaid balance (same as a position read).

API equivalent: GET /v1/agent/loads/{loadNumber}/trip-stats · SDK: getTripStats(loadNumber)

When to call

  • The load is DELIVERED and the user wants post-trip scoring, CO₂/fuel estimation or detention evidence.
  • Mid-trip it also works — it returns the trip so far.

When NOT to call

  • To find where the truck is right now — that is get_load_position, which returns the live position and ETA. get_trip_stats returns totals over the journey.

Parameters

Parameter Type Required Meaning
loadNumber string yes PingPoint load number, e.g. LD-2026-123456.

Example

Request: { "loadNumber": "LD-2026-051784" }

Response (HTTP 200):

{
  "loadNumber": "LD-2026-051784",
  "loadId": "3b9f6a2e-1c47-4d8a-9e02-7f5b1c8d4a63",
  "stats": {
    "dataPoints": 4785,
    "durationSeconds": 69329,
    "estimatedDistanceMiles": 486.591,
    "avgSpeedMph": 25.27,
    "maxSpeedMph": 88.22,
    "hardAccelCount": 280,
    "hardBrakeCount": 168,
    "cityMilesPct": 9.96,
    "highwayMilesPct": 88.65,
    "parkedTimePct": 53.65,
    "nightPct": 44.7,
    "coveragePct": 100,
    "firstAt": "2026-08-18T16:53:25.000Z",
    "lastAt": "2026-08-19T12:08:54.000Z"
  }
}

Field definitions

Field Unit Definition
dataPoints count GPS pings with a fix recorded for this load.
durationSeconds s lastAt − firstAt.
estimatedDistanceMiles miles Haversine over the full recorded track.
avgSpeedMph mph Over the whole span, stops included.
maxSpeedMph mph Maximum recorded ground speed.
hardAccelCount count Speed gain over +15 mph/min while moving faster than 20 mph.
hardBrakeCount count Speed drop under −20 mph/min while moving faster than 20 mph.
cityMilesPct % 0–100 Share of miles driven at 5–45 mph.
highwayMilesPct % 0–100 Share of miles driven above 45 mph.
parkedTimePct % 0–100 Share of pings at ≤ 5 mph (parked or idling).
nightPct % 0–100 Share of pings between 23:00 and 07:00 UTC.
coveragePct %, capped at 100 dataPoints vs. a one-ping-per-minute expectation over the span.
firstAt / lastAt ISO 8601 UTC First/last recorded ping; null when the load has no pings yet (all stats zero/null then).

Errors

Same as a position read:

Code Meaning
401 Missing or invalid key.
402 INSUFFICIENT_FUNDS Balance can't cover $0.02 — nothing charged.
403 The load belongs to another account.
404 No such load.
422 UNKNOWN_BROKER The key's account is not registered on PingPoint.