Picogrid Legion Platform API: response documents into the canonical model

The API exposes entities, their locations, events and tasking. The adapter reads the first three, and dispatches on the shape of the document rather than on a caller-supplied type tag, because a tag would be a second source of truth about what is being held.

The implementation is pinned to an exact retrieved specification document, recorded with its host, size, retrieval date and hash, because a vendor API can change between one deployment and the next in a way a ratified standard cannot.

The specification's declared version string is not a usable change signal, since it stays constant while paths beneath it change. The document hash is the signal, and the published pin records it so a later reader can re-fetch and compare.

A deployment that already runs a sensor integration platform has an existing inventory of entities and observations, and reading it directly avoids re-instrumenting sensors that are already reporting.

Because the adapter translates documents a caller fetched rather than owning a client, an operator's own authentication, network policy and rate limits stay in the operator's code where they are visible.

The result is that third-party sensor observations arrive in the same canonical objects as radar, imagery metadata and cooperative broadcasts, and are correlated in the audited fusion layer rather than upstream of it.

The adapter takes one already fetched JSON document. It does not own, and must not acquire, an HTTP client, an access token, a retry policy, a page cursor or a base address. Transport is where state lives, and an adapter holding state is an unaudited fusion layer.

Four document shapes are in scope. An entity document becomes an Entity, and an Event too when a latest location is embedded. A location document becomes an Event, and the Entity too when the entity block is embedded. An event document becomes an Event. A list of locations becomes an Entity and a Track whose samples are in payload order, with completeness recorded.

The coordinate handling is the sharpest detail in the adapter. The position object is shaped like a common geographic format but its default reference system is geocentric metres from the centre of the Earth, so reading the coordinates as longitude and latitude would place every contact somewhere nonsensical while producing perfectly well formed output. The source coordinates are therefore re-emitted verbatim with their reference system name, and the geodetic position is computed beside them rather than instead of them. One reference system in the enumeration is defined in no document and is refused by name, because guessing its axis order would yield a plausible wrong position rather than an error.

Pagination is treated as framing, not as history. One page is one payload and becomes one Track labelled as partial. The adapter does not follow the next link and does not stitch pages together, and it declines the four joins the API offers, because each is a second request and a correlation.

Absence is read in three ways because the API expresses three different facts: a key that is not there is nobody having said anything, a key present and null is the source stating it has no value, and a key present and empty is ambiguous and parked verbatim. Fields missing because an embedded block is a structural subset are recorded as such and never counted as statements of ignorance.

An unparseable observation time refuses the whole document with a written reason and never falls back to the receipt clock, because a document stamped with the wrong minute is a track that drifts for reasons nobody can find, whereas a refused document is visible in the caller's error handling.