API reference

Five read-only JSON endpoints for any point in Flanders, one of them (history) over our daily GIPOD archive for Antwerp and 15 km around it. Bearer-token auth, quota headers on every response, deterministic output.

Version 1.1.0. Base URL https://stadiq.app/api/v1. Machine-readable: OpenAPI 3.1.

Contents

Quick start

  1. Get a key

    Create one on Get started. It is shown once; store it as a secret.

  2. Send it on every request

    Header
    Authorization: Bearer sq_live_…
  3. Verify

    A 200 with X-RateLimit-Remaining in the headers means the key works.

    Request
    curl -H "Authorization: Bearer sq_live_…" \
      "https://stadiq.app/api/v1/disruptions?lat=51.2194&lng=4.4025"

Endpoints

GET /locations

The locations saved on your account.

No parameters.

Returns: id, name, address, lat, lng, label, isPrimary.

GET /disruptions

Road works within 2 km of the point and transit disruptions affecting it.

locationId
One of your location ids. It cannot be combined with lat/lng.
lat, lng
Any point in Flanders.

Returns: summary counts, construction[], transit[].

GET /history

GIPOD works and occupations captured in the daily archive within radius_m (max 1000, default 500) of the point, including every published change to their start, end or status. Covers Antwerp and 15 km around it from 11 April 2026. Paginated with limit and offset.

address
A street address, geocoded. Use instead of lat/lng.
lat, lng
A point within 15 km of Antwerp centre, radius included. Further out returns 422 outside_archive_area.
locationId
One of your location ids, same rule.
radius_m
Metres around the point, 1 to 1000. Default 500.
since, until
Window as YYYY-MM-DD. Defaults: archive start and today.
limit, offset
Page size (max 200, default 50) and the offset from pagination.next_offset.

Returns: coverage (capture days, missing_days, live_gipod), pagination, works[] with revisions[], source with the licence attribution.

GET /briefing

Risk level, key facts, and the best and worst windows in the next 24 hours.

locationId
One of your location ids. It cannot be combined with lat/lng.
lat, lng
Any point in Flanders.

Returns: risk, headline, keyFacts[], bestWindow, worstWindow, nextRushPeak, unavailableFeeds[], sources[].

GET /air-quality

Legacy and not actively developed: the latest reading from the nearest IRCELINE station, plus LEZ status. Measured values only.

locationId
One of your location ids. It cannot be combined with lat/lng.
lat, lng
Any point in Flanders.

Returns: reading, thresholds, compliance, lez.

Every location-scoped endpoint needs a target: locationId or both lat and lng. An API-only account has no saved locations, so it uses coordinates.

Example response

GET /disruptions for Groenplaats, abridged. Values are illustrative.

Response, abridged
{
  "radiusKm": 2,
  "summary": { "activeWorks": 3, "plannedWorks": 5, "transitDisruptions": 2 },
  "construction": [ … ],
  "transit": [ … ],
  "retrievedAt": "2026-08-16T14:02:11.000Z"
}
Full response (34 lines)
{
  "location": { "lat": 51.2194, "lng": 4.4025 },
  "radiusKm": 2,
  "summary": {
    "activeWorks": 3,
    "plannedWorks": 5,
    "upcomingWorks14d": 1,
    "transitDisruptions": 2,
    "highSeverityTransit": 1
  },
  "construction": [
    {
      "id": "gipod-…",
      "description": "Rioleringswerken Nationalestraat",
      "status": "In uitvoering",
      "lat": 51.2181,
      "lng": 4.3996,
      "distanceKm": 0.21,
      "startDate": "2026-08-03",
      "endDate": "2026-09-14"
    }
  ],
  "transit": [
    {
      "id": "o-…",
      "title": "Omleiding tram 4: Sint-Jansplein",
      "lines": ["4"],
      "severity": "medium",
      "estimatedDelayMin": 0,
      "endDate": "2026-08-20"
    }
  ],
  "retrievedAt": "2026-08-16T14:02:11.000Z"
}

GET /history near the Desguinlei, abridged, from a test copy of the archive. When coverage.state is unavailable, works is empty because nothing was captured, not because nothing happened.

History response, abridged (29 lines)
{
  "query": { "lat": 51.1931, "lng": 4.4033, "radius_m": 1000, "since": "2026-09-01", "until": "2026-11-08" },
  "coverage": {
    "state": "gaps",
    "archive_start": "2026-04-11",
    "capture_days": 54,
    "missing_days": ["2026-10-25", "2026-10-26", "…"],
    "partial_capture_days": 54,
    "live_gipod": { "answered": true, "complete": true, "works_now": 77, "not_yet_archived": 74 }
  },
  "pagination": { "total": 3, "limit": 50, "offset": 0, "next_offset": null },
  "works": [
    {
      "gipod_id": "12350353",
      "title": "Gemengde markt\nDesguinlei",
      "kind": "occupation",
      "status": { "published": "Lopende", "mapped": "unknown" },
      "first_seen": "2026-04-11",
      "last_seen": "2026-10-24",
      "start": "2026-10-23T09:30:00Z",
      "end": "2027-04-23T14:30:00Z",
      "revisions": [
        { "seen_at": "2026-09-04", "field": "end", "from": "2027-02-26T15:30:00Z", "to": "2027-03-05T15:30:00Z" }
      ],
      "distance_m": 777
    }
  ],
  "source": { "name": "GIPOD", "licence": "Modellicentie Gratis Hergebruik Vlaanderen v1.0", "attribution": "Bevat overheidsinformatie, …" }
}

Errors

Errors return JSON with error (the code) and message (what to do about it).

400 missing_target, invalid_coordinates
Neither locationId nor a valid lat/lng pair was given.
401 missing_key, invalid_key
No Bearer token, or an unknown or revoked key.
403 plan_required
The account's plan does not include API access.
404 location_not_found
That locationId does not belong to your account.
422 outside_service_area
The point is outside the Flemish Region. Brussels and Wallonia are not covered.
422 outside_archive_area
History only: the point plus radius reaches past the 15 km archive circle around Antwerp.
422 address_not_found
History only: the address could not be placed in Belgium.
429 quota_exceeded
Daily quota reached. Resets at 00:00 UTC.
502 upstream_error
A source (GIPOD, De Lijn, IRCELINE) failed. Retry shortly.

Quotas and caching

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Quotas reset at 00:00 UTC; the free developer tier and the paid plans are on the pricing table. Responses are cacheable for 60 seconds.

What the contract guarantees

  • Coverage is the Flemish Region; Brussels and Wallonia are not covered. A point outside it returns 422, rather than an empty result that could be read as nothing happening.
  • When a source is down or incomplete, unavailableFeeds names it, and a briefing with no other risk signal reports unknown rather than low. Missing data is never presented as an all-clear.
  • /history returns a coverage block with every day the archive missed. When no day of the window was captured, coverage.state is unavailable and the empty list means unknown.
  • /disruptions carries retrievedAt, the moment the sources were read. The paths are versioned under /api/v1 and the OpenAPI spec carries its own version number.
  • History starts on 11 April 2026 and is not the full history of GIPOD. Days before 9 November 2026 hold only a slice of the works; coverage says so. A record that looks wrong: mail the GIPOD id.
  • The same coordinates return the same computed numbers. No generated text is part of the contract.
  • Air-quality responses carry measured values only; modelled figures are excluded.