Podium metric timeline API

Podium stores vessel data as timelines: a series of timestamps, each carrying one or more metrics. Every vessel has a set of them. This surface lets you list the timelines held for your vessels and pull the metrics off any one of them for a time range.

Three endpoints, in the order you will use them.

Endpoint	Answers
`GET /api/tmln/v2/cf/timeline/info`	Which timelines exist across the whole account
`GET /api/tmln/v2/cf/timeline/info/{imo}`	Which timelines exist for one vessel
`POST /api/tmln/v2/cf/timeline/extract`	What the metrics are on one timeline, over a time range

All three are on https://aviso-api.stratumfive.com and take a bearer token. See Podium Authentication.

The contract titles this surface Podium Metric Timeline I/O. It is the same API.

What identifies a timeline

Four values together identify a timeline, and you need all four to extract from one.

Part	Meaning
`accountId`	Your account
`entityId`	The vessel, as Podium numbers it. This is not the IMO
`tmlnSeriesType`	Which kind of series: `ingested`, `ndr` or `voyage_rpt_summary`
`tmlnDatasource`	Which feed it came from

You do not assemble these yourself. The two info calls return them, so list before you extract.

The three series types

ingested holds raw data as the sensor provider sent it. Metric names here are the provider's own, so they vary between one datasource and the next.

ndr holds noon report data, at whatever resolution the source reports. That is usually one entry per 24 hours.

voyage_rpt_summary holds voyage-level data at intervals that map to voyage reporting.

Datasources

ingested timelines name the sensor provider they came from: inm_c, ais_spire, dsas, veinland, veems, mac or danelec, and otis. We add to this list as new providers are onboarded, so take what the info call returns as current.

Listing timelines

Each entry in tmlnInfoSet carries the four identifying values plus the vessel's name and IMO. Two optional blocks come back when you ask for them.

Parameter	Adds
`includeStats=true`	`tmlnStats`: how many timestamps the timeline holds, and its earliest and latest
`includeChanges=true`	`tmlnChanges`: the timeline's key, and the changes recorded against it
`changesSince`	Bounds `tmlnChanges` to changes at or after this UTC timestamp

changesSince comes back echoed inside each tmlnChanges block, so you can confirm which window the response was built against.

Ask for stats before you ask for metrics

tmlnStats tells you the earliest and latest timestamps a timeline holds. Reading that first stops you requesting a range the timeline has no data for, and tells you how much to expect back.

To narrow to one vessel, use the by-IMO form. The by-IMO form takes includeChanges and changesSince like the account-wide listing, and adds includeStats, seriesType and datasource of its own.

seriesType and datasource restrict the response to matching timelines.

Extracting metrics

Send the identifying values from the info response, plus the range you want.

limit caps how many timestamps come back. includeDebugInfo adds processing detail to the response, which is worth having while you are working out a query and worth dropping once it runs.

entityId is Podium's vessel number, not the IMO

entityId is the value the info endpoints return. Sending an IMO in that field returns an empty result, not an error.

Podium Authentication

Exchanging client credentials for the bearer token these endpoints take.

Podium

How this sits alongside the Insights modules, and why it is badged.

Vessel Positions

Consolidated positions, when the question is where a vessel is rather than what it reported.

Podium Metric I/O

What identifies a timeline#

The three series types#

Datasources#

Listing timelines#

Extracting metrics#

Related#

What identifies a timeline

The three series types

Datasources

Listing timelines

Extracting metrics

Related