Track Usages

Track usages record the traffic an asset has carried: the tonnage and train movements that pass over a section of track or through a switch. An asset describes the physical thing; a track usage describes the load it has seen over time, one record per movement. This data drives wear, fatigue, and degradation analysis. The more accurately you capture what ran where, the better the platform can reason about how an asset is ageing.

At a glance

• Represents: a single train movement or tonnage event against an asset
• Body: a JSON array of track-usage objects
• Keyed by: id — your external identifier, and the upsert key
• Belongs to: an asset (assetId)
• References: the shared geolocation concept

Tip

The full field list, required vs. optional flags, and a runnable example payload are in the API Reference under Track Usage Import (POST /v2/trackusages).

What it represents

Each record captures a movement at a point in time: when it happened, what kind of usage it was, and how much load it carried. The usage is one of three types, and that choice frames the rest of the record:

• Section tonnage and switch tonnage — carry weight and axle-load figures.
• Switch movement — describes how traffic passed through a switch, including its position and direction.

A track usage always belongs to an asset, named by its assetId. That asset must already exist, or be imported in the same batch — see models reference each other by identifier. The optional geolocation block pins the movement to a stretch of the network, which is useful when usage varies along a single asset.

Using it

• Import the asset before (or alongside) the usages that reference it. An assetId the platform doesn’t recognise passes request validation but fails at job time — see Common Errors.
• Keep each id stable and unique within a request. Re-importing the same id updates that record in place rather than adding a duplicate movement.
• Usages accumulate: you typically send a stream of movements over time, so an accurate movementDateTime and usage type are what make the history meaningful.