A traffic sensor API is usable when both sides agree on the meaning of each record, not merely when JSON arrives. Define observation time, lane and movement identity, units, quality states and replay behavior before connecting the feed to operational reporting.
Table of Contents
Define the record before choosing the transport
A traffic sensor application programming interface, or API, can deliver counts, individual passages, tracks or alarms. Those are different record types. A five-minute count cannot be treated as an individual event, and a track update cannot be counted repeatedly as new traffic.
ONVIF Profile M defines metadata and event capabilities relevant to analytics, including object classification and counting interfaces when supported. A profile or protocol helps exchange information, but the project still needs a definition of the delivered traffic data.
The ONVIF integration guide addresses device and client functions. A traffic project also needs an application-level contract for its sensor data.
Use an explicit event example
An illustrative passage record might contain:
{
"event_id": "siteA-20261105-000042",
"observed_at": "2026-11-05T12:00:03.250Z",
"received_at": "2026-11-05T12:00:03.410Z",
"lane_id": "northbound-2",
"geometry_version": "2026-10-15",
"event_type": "passage",
"speed": 12.4,
"speed_unit": "m/s",
"quality": "valid"
}This is a proposed contract example, not an OMNI product API. Its value is the distinction between measurement and receipt time, a stable event identity, explicit units and a versioned lane definition.
Decide how the consumer handles exceptions
| Condition | Contract rule to define | Why it matters |
|---|---|---|
| Duplicate event | Stable identity and idempotent handling | Prevents double counting after retry |
| Late arrival | Allowed lateness and aggregate revision | Preserves the correct time window |
| Missing interval | Explicit missing or unavailable state | Prevents false zero-demand periods |
| Invalid speed | Quality state and reason | Prevents a numeric placeholder entering averages |
| Geometry change | Versioned lane and movement mapping | Keeps old and new records interpretable |
| Schema change | Compatibility and deprecation policy | Avoids silent consumer failure |
Define interval boundaries for aggregated data. For example, a half-open interval includes its start and excludes its end, preventing a boundary event from appearing in two windows. The choice must be consistent across producer and consumer.
Time-zone handling also belongs in the contract. Store an unambiguous time reference and treat local reporting windows separately, especially where daylight-saving changes affect a day.
An example makes the states concrete. A sensor that reports 42 vehicles in the 12:00–12:05 window, then returns an error for 12:05–12:10, has not reported zero traffic. The consumer should store the second interval as missing, keep the error or quality code, and exclude it from a completeness calculation rather than treating it as a quiet period.
Make replay and outage recovery routine
A feed should explain how a client resumes after disconnection. A cursor, sequence or time-range query can support recovery, but the method needs retention limits and ordering rules. Replayed historical data should not become a new real-time alert merely because it arrived again.
Test the consumer with a short fixture containing normal, duplicate, late, invalid and missing records. The expected result should be known before the test. The traffic data-quality article develops downstream completeness and aggregation checks.
For a smart-city transportation platform, assign ownership of the lane registry and data dictionary. A sensor vendor cannot maintain the meaning of a lane after road works unless the change reaches the configuration process.
The deliverable is a stable interpretation of traffic over time, with a recovery path when systems or road geometry change. Place the interface specification, sample records and expected test outputs in the project resources so a new consumer can be validated without reverse-engineering the feed.
FAQs
Can an HTTP success response prove that a count was accepted correctly?
No. It proves only the defined request-level behavior. The receiving system must also validate schema, units, identity, time range and duplication rules.
Should missing intervals be returned as zero traffic?
No. Zero is a valid observation of no traffic, while missing means the observation is unavailable. Keep these states distinct in the API and downstream aggregates.
Can lane IDs be reused after a road layout change?
Only with an explicit version or time-bounded mapping. Otherwise historical observations may be interpreted using a new geometry that did not exist when they were recorded.
What should an API version change preserve?
Preserve the meaning of existing fields, publish a deprecation window and keep old and new lane mappings interpretable. A schema version that silently changes units or identifiers breaks historical comparisons.
