v4

latestOpenAPI 3.1.0Proprietary2026-08-034715226.2 KB

events

List traffic events

Paginated list of traffic events with filters. Free plan requires jurisdiction parameter.

Ordering (not configurable): severity first — critical, major, moderate, then everything else — and within a severity band by last_updated descending, tie-broken by id descending. Because last_updated is a content-change time, the top of a band is what changed most recently, not what we polled most recently.

The id tiebreak matters for pagination: last_updated alone is not a total order (events land in batches that share a timestamp), so without it two pages could repeat or skip rows.

Batch lookup: pass ?ids=id1,id2,... to fetch a known set of events by id. When ids is set, all other filters except plan data delay are ignored and pagination is disabled — the response always returns the full set in one page. Archived events are filtered per plan: non-analytics plans (allow_analytics: false) receive only events whose effective start_time is within the last 7 days. Active events are always returned regardless of age. total reflects the post-filter count. The batch size is capped by the plan's max_batch_size.

get/events

Query parameters

idsstring

Comma-separated event IDs for batch lookup. Mutually exclusive with the filter parameters below (when present, other filters are ignored). Bounded by the plan's max_batch_size.

jurisdictionstring

Filter by jurisdiction code (e.g., GA, ON, CA). Required on Free plan.

Auto-expansion: querying a state's primary code that has WZDx/CWZ or sub-state regional siblings (see GET /jurisdictions/groups) is expanded transparently to include all members. For example, ?jurisdiction=CA returns rows from CA, WZDX_CA, and 511SF.

To opt out, query a non-primary code directly (?jurisdiction=WZDX_CA returns WZDx-only rows) or pass a comma-separated list explicitly (?jurisdiction=CA,WZDX_CA), which bypasses expansion and matches each code literally.

limitinteger

Results per page (capped by plan)

offsetinteger

Pagination offset

bboxstring

Bounding box: minLng,minLat,maxLng,maxLat

latnumber

Latitude for radius search

lngnumber

Longitude for radius search

radius_kmnumber

Radius in km (used with lat/lng).

Capped at 200 when combined with group. A group expands to many feature types, and a wide radius over all of them cannot be served inside the request budget, so the combination returns 400 rather than timing out. Lower the radius, or query a single type — single-type radius searches have no limit.

typestring

Filter by event type

sub_typestring

Filter by second-level classification (e.g. accident). Additive — omit to match all sub_types. See the sub_type enum on the TrafficEvent schema for the full vocabulary.

Filter by underlying operational cause, independent of type — e.g. cause=accident returns accident-caused events whether the source modeled them as an incident, closure, or construction. Additive; omit to match all causes. See the cause enum on the TrafficEvent schema.

severity'minor' | 'moderate' | 'major' | 'critical'

status'active' | 'archived' | 'all'

active (default) returns active events, archived returns archived events only, all disables the filter and returns both.

Plans without analytics access (allow_analytics: false) may request archived or all only when paired with a start_time_from no older than 7 days — otherwise the request is rejected with 403. Plans with analytics access have no such restriction.

roadstring

Filter by road name (partial match)

start_time_fromstring date-time

Lower bound (inclusive, RFC3339) on the event's start time. Matches COALESCE(start_time, created_at), so events whose upstream feed never populated start_time still surface via their ingest time. When either time-range parameter is set and status is omitted, the default flips from active to all so archived (historical) events are returned. Lookback beyond the last 7 days requires a plan with analytics access (allow_analytics: true).

start_time_tostring date-time

Upper bound (inclusive, RFC3339) on the event's start time. See start_time_from for column semantics. Without a start_time_from companion the range is treated as open-ended on the lower end and therefore counts as deep history (analytics plan required).

Response

Paginated events

has_moreboolean

limitinteger

offsetinteger

totalinteger

Example response

{
  "attribution": [
    {
      "attribution": "© Dirección General de Tráfico (DGT) — licensed under CC BY 4.0",
      "license": "CC-BY 4.0",
      "license_url": "https://creativecommons.org/licenses/by/4.0/",
      "source_code": "ESP",
      "source_name": "Spain — DGT National Access Point"
    }
  ]
}