API documentation

Quickstart

Create an evaluation account, generate a key in your dashboard, and request pilot activation for live feeds. Synthetic examples require no account.

curl 'https://roadworkdata.com/api/sample?format=cwz'

For activated accounts, replace the sample path with a filtered live query:

curl --get 'https://roadworkdata.com/v1/work-zones' \
  --data-urlencode 'format=cwz' \
  --data-urlencode 'state=california' \
  --data-urlencode 'limit=100' \
  --header 'X-API-Key: YOUR_API_KEY'

Use X-API-Key or Authorization: Bearer YOUR_API_KEY. Keep keys on your backend. Keys entered below remain in this page's memory and are never stored in browser storage.

Endpoints

Source quality and identity

GET /v1/quality?days=7&feed_id=caltrans_d07 reports per-source completeness, geometry flags, freshness and identity decision counts. Omit feed_id for all permitted sources. The identity window accepts 1–30 days; it begins when telemetry is installed, with no historical backfill.

Inventory counts present stored observations, including ended events, with missing history separate. Known impact or lane status counts usable closure information; empty or unknown fields do not count. Identity counters measure observed matching decisions, ambiguity, changing source IDs and reappearances, not verified accuracy. Baselines are excluded; failures and HTTP 304 responses are not sampled. A zero sample count means telemetry is unavailable.

Matching gives known upstream identities priority and requires unique candidates on both sides. Source array ordering does not select which event keeps an ID. Current source IDs and historical aliases are retained separately.

Formats and licensing

CWZ-compatible output changes only FeedInfo's license constraint: it uses service evaluation terms rather than declaring the combined output CC0. RoadEventFeature validation remains the published CWZ 1.0 validation. This is an explicit compatibility profile, not full conformance to the unmodified CWZ schema.

CWZ-compatible schema · Original CWZ schema · WZDx schema

WZDx output omits the optional global license field instead of applying CC0 to the service output. Source licenses and rights status are retained in feed_info.data_sources. Review evaluation terms and source notices.

The x_work_zone_api extension reports exclusions, source identifiers, freshness, and geometry transformations. With extensions=false, use response headers for pagination, export counts, and the CWZ schema profile. The service never fills missing required dates with guesses. Unrepresentable observations remain in the internal normalized representation.

Geometry is publisher-provided. Endpoint conversion to a straight line does not reconstruct a road path. Advanced ID stabilization, cross-source deduplication, and road matching are not production guarantees.

Filters and pagination

Use feed_id, state (such as california), bbox=west,south,east,north, after, before, status, and include_missing. Times accept RFC3339 or positive epoch seconds. Bounding boxes test rectangle overlap, not exact road intersection.

List queries accept limit=1…500. Follow the HTTP Link entry with rel="next" or x_work_zone_api.next_offset until exhausted. Offsets refer to scanned candidates; concurrent ingestion does not provide a consistent pagination snapshot.

Default queries omit ended, canceled, and completed events. Scheduled-active means the scheduled window overlaps now; it does not confirm actual activity. Inspect feature x_work_zone_api.feed_last_success, source_updated, feed_stale, source_timestamp_stale and freshness_threshold_seconds. A null source_updated means the publisher timestamp is unavailable, even when source_timestamp_stale is false. Successful HTTP 304 validation refreshes feed_last_success without changing event last_seen. Missing observations carry missing_since and status unknown unless the publisher explicitly reported cancellation/completion. Default queries omit them after two poll intervals; include_missing=true retains them subject to the other filters. Feed failures do not themselves mark events missing. Keep extensions enabled to receive this per-event evidence.

Quotas and errors

Account quotas use UTC calendar months. Requests admitted after authentication and entitlement checks consume allowance, including error responses. Authentication failures and rejected quota requests do not. Bytes and complete-export counts are also measured; these are pilot usage counters, not monetary charges.

• 400 — invalid query or request body.
• 401 — missing, invalid, or revoked key.
• 403 — account activation or entitlement required.
• 404 — unavailable observation or key.
• 422 — an observation cannot be represented in the requested format.
• 429 — per-minute or monthly quota reached; no automatic overages.
• 503 — required service unavailable.

X-Quota-Limit and X-Quota-Remaining report the monthly allowance. A per-minute rejection includes Retry-After. Operator development keys are separate from customer accounts and bypass customer quotas.