API reference

Every CLARA endpoint on one page: parameters, response fields, an abridged example and the errors each one can return. CLARA serves street-level air quality, pedestrian wind comfort and thermal comfort, modelled at up to 1×1 m, as JSON over HTTPS.

The base URL for everything below is https://api.clara.city/v1. Responses are JSON (application/json), errors are RFC 9457 problem documents (application/problem+json), and all timestamps are ISO 8601 UTC. The machine-readable contract lives in two OpenAPI files: the main API and the Maps API. If prose and specification ever disagree, the specification wins.

Data responses share one envelope: city (which city answered, present when the location falls inside a covered city), location (the resolved address and the coordinates actually used) and meta (which dataset answered and how the location was sampled). The getting started guide walks through reading one.

Authentication

Every data endpoint takes an API key as a bearer token, in either header:

Authorization: Bearer YOUR_CLARA_KEY
X-API-Key: YOUR_CLARA_KEY

Secret keys (clara_sk_) stay on your server; publishable keys (clara_pk_) may sit in a browser page and are checked against the origins registered on them. Four endpoints need no key at all: /health, /cities (including /cities/{city}) and /scales. Map tiles use signed URLs instead of a key, so map libraries can fetch them without custom headers.

Keys are scoped to cities and products, and rate limited per minute with a separate daily report quota. GET /v1/key shows a key's exact scope. The long form, including how to get a key and how origin registration works, is in the getting started guide.

GET/v1/health

No key required. Not rate limited.

Confirms the service is up and reports the running API version. Useful as a monitoring target or a connectivity check before anything else.

Response fields

Example

{
  "service": "clara-api",
  "status": "ok",
  "version": "1.0.0",
  "time": "2026-08-20T10:15:42Z"
}

GET/v1/cities

No key required.

The machine-readable city index: every city CLARA covers, with its bounding box and the products it has. Called with a key, each entry additionally carries authorized, whether that key is scoped to the city. The response is cacheable for an hour (Cache-Control: public, max-age=3600).

Parameters

Response fields

Example

{
  "generated_utc": "2026-08-20T10:15:42Z",
  "cities": [
    {
      "id": "brussels",
      "name": "Brussels",
      "country": "BE",
      "timezone": "Europe/Brussels",
      "bbox": [4.30421, 50.79655, 4.41729, 50.87949],
      "products": {
        "geocode": true, "historical": true, "realtime": true,
        "forecast": true, "reports": true, "map": true
      },
      "map": {
        "layers": ["thermal", "wind", "air", "buildings"],
        "forecast_hours": 48,
        "cadence": "hourly"
      }
    },
    { "id": "ravenna", "...": "..." }
  ]
}

GET/v1/cities/{city}

No key required.

Everything the index reports for one city, plus the exact coverage boundary as a GeoJSON Feature with a Polygon geometry ([lon, lat] coordinate order). Draw it on a map, or use it to pre-filter locations before spending data requests. Cacheable for an hour; it changes only when coverage changes.

Parameters

Response fields

Example

{
  "id": "brussels",
  "name": "Brussels",
  "country": "BE",
  "timezone": "Europe/Brussels",
  "bbox": [4.30421, 50.79655, 4.41729, 50.87949],
  "products": { "geocode": true, "historical": true, "...": "..." },
  "reference_year": 2025,
  "attribution": "CLARA by BuildWind",
  "boundary": {
    "type": "Feature",
    "properties": {},
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[4.31282, 50.87911], [4.31355, 50.87801], "..."]]
    }
  }
}

Errors: not_found (404).

GET/v1/scales

No key required.

What each metric can be plotted as, and how to colour it. A view is what to plot: wind can be drawn as the mean pedestrian speed, as the gusts, or as the combined comfort and danger classes; air as the index or as one pollutant. A scale is how to colour one view. These are the definitions behind every coloured value CLARA renders, published once so clients never hardcode them. Cacheable for a day; a scale changes only when its issuing authority revises it.

Parameters

Response fields

Example

GET /v1/scales?metric=wind

{
  "views": [
    { "id": "comfort-safety", "metric": "wind", "name": "Wind comfort and danger",
      "fields": ["Ucomfort", "Ugust"],
      "field_labels": { "Ucomfort": "Wind", "Ugust": "Gust" },
      "scales": ["wind-nen8100", "wind-cvd"],
      "default_scale": "wind-nen8100", "default": true },
    { "id": "mean", "metric": "wind", "name": "Wind", "fields": ["Ucomfort"],
      "field_labels": { "Ucomfort": "Wind" },
      "scales": ["wind-mean-rainbow"], "default_scale": "wind-mean-rainbow" },
    { "id": "gust", "metric": "wind", "name": "Gust", "fields": ["Ugust"],
      "field_labels": { "Ugust": "Gust" },
      "scales": ["wind-gust-rainbow"], "default_scale": "wind-gust-rainbow" }
  ],
  "scales": [
    { "id": "wind-nen8100", "view": "comfort-safety", "kind": "classes",
      "name": "Standard", "default": true },
    { "id": "wind-cvd", "view": "comfort-safety", "kind": "classes",
      "name": "Colour-blind" },
    { "id": "wind-mean-rainbow", "view": "mean", "kind": "gradient",
      "name": "Standard", "default": true },
    { "id": "wind-gust-rainbow", "view": "gust", "kind": "gradient",
      "name": "Standard", "default": true }
  ]
}

GET/v1/scales/{scale}

No key required.

The full definition of one scale: classes in display order with labels, colours and bounds, so a legend and a map style come from one fetch. kind says how to consume it. Comfort classes also carry when, the machine-readable form of their condition, so the classification can be built rather than reimplemented from the prose. Index scales such as air-belaqi carry per-pollutant thresholds instead.

Parameters

Response fields

Example

{
  "id": "belaqi",
  "name": "BelAQI air quality index",
  "authority": "IRCEL-CELINE (Belgium)",
  "description": "Belgian air quality index, 1 (Excellent) to 10 (Horrible). The hourly value is the worst per-pollutant class.",
  "classes": [
    { "value": 1, "label": "Excellent", "color": "#012BF5" },
    { "value": 2, "label": "Very good", "color": "#2D9BF8" },
    { "...": "..." },
    { "value": 10, "label": "Horrible", "color": "#8E2695" }
  ],
  "no_data_color": "#aaa4a4",
  "thresholds": {
    "no2":  [10, 15, 20, 30, 40, 45, 50, 60, 75],
    "pm25": [3.5, 7.5, 10, 15, 20, 35, 50, 60, 75],
    "pm10": [10, 20, 35, 45, 60, 80, 95, 110, 140]
  }
}

Errors: not_found (404).

GET/v1/key

Requires a key. Any product.

Echoes the presented key's label, type, city and product scope, and limits. The first call to make after receiving a key: it confirms the key works and shows exactly what it can reach, so you never have to guess what you were given.

Response fields

Example

{
  "label": "your-company",
  "type": "sk",
  "cities": ["brussels"],
  "products": ["geocode", "historical", "realtime", "forecast", "reports"],
  "limits": { "rate_per_min": 100, "reports_per_day": 100 },
  "created": "2026-08-20",
  "expires_at": null
}

Errors: unauthorized (401), forbidden (403).

GET/v1/geocode

Requires a key with the geocode product.

Resolves a free-text address to coordinates, as a helper for calling the data endpoints. Results are for CLARA queries only: they must not be stored or redistributed, and CLARA does not offer geocoding as a standalone service. results may be empty when nothing matches.

Parameters

Response fields

Example

{
  "query": "Chaussée de Waterloo 481, Ixelles",
  "results": [
    {
      "address": "Chaussée de Waterloo 481, 1050 Ixelles",
      "lat": 50.82068,
      "lon": 4.35821,
      "relevance": 1.0,
      "covered": true,
      "city": "brussels"
    }
  ]
}

Errors: validation_error (400), unauthorized (401), forbidden (403), rate_limited (429), upstream_error (502).

GET/v1/historical/stats

Requires a key with the historical product.

The reference-year statistics for one location: air quality, wind comfort and thermal comfort, each with a 0 to 10 rating and the full statistics behind it. Provide either address or both lat and lon; supplying both at once returns 400 validation_error. Coordinates are rounded to 5 decimals before processing.

Any location in Belgium is served. Inside the Brussels high-resolution zone (boundary at GET /v1/cities/brussels) the answer comes from the street-level model; elsewhere in Belgium it comes from a lower-resolution nationwide dataset. meta.dataset reports which one answered. Locations outside every covered area receive 422 outside_coverage.

By default no radius is applied and the answer is the value at the location: the grid cell containing the point, or, when the point falls inside a building, as geocoded addresses normally do, the outdoor cells at the nearest distance plus half a grid cell. Building-interior cells are never read. meta.sampling says which rule was used. Supplying radius averages deliberately over that area instead, with no widening; nationwide answers always use the cell containing the location and ignore radius.

Parameters

Response fields, envelope

Response fields, air

Air quality on the BelAQI scale (GET /v1/scales/air-belaqi). The hourly value is the worst of NO2, PM2.5 and PM10 per cell, averaged over the sampled cells. "Good air" means BelAQI class 1 to 4.

Response fields, wind

Pedestrian wind comfort. Each hour is assigned the worse of the comfort-wind class (from Ucomfort) and the gust class (from Ugust); class definitions at GET /v1/scales?metric=wind.

Response fields, thermal

Thermal comfort from the hourly Universal Thermal Climate Index (UTCI, degrees C). A comfortable hour sits in the "no thermal stress" band, 9 to 26 degrees C (GET /v1/scales/thermal-utci). The block is omitted when the dataset carries no UTCI data.

Example

{
  "city": { "id": "brussels", "name": "Brussels", "country": "BE" },
  "location": { "address": null, "lat": 50.82068, "lon": 4.35821 },
  "meta": {
    "dataset": "brussels_extended",
    "reference_year": 2025,
    "sampling": "nearest_outdoor",
    "distance_m": 7.5,
    "n_cells": 3,
    "hours": 8760,
    "generated_utc": "2026-08-20T09:12:04Z"
  },
  "air": {
    "rating": 7.3,
    "score": 6.8,
    "label": "Good",
    "good_pct": 72.7,
    "dominant_pollutant": "NO2",
    "annual_mean_ugm3": { "no2": 21.4, "pm25": 7.9, "pm10": 14.7 },
    "...": "..."
  },
  "wind":    { "rating": 8.6, "calm_pct": 96.2, "...": "..." },
  "thermal": { "rating": 5.7, "tropical_nights": 8, "...": "..." }
}

Errors: validation_error (400), unauthorized (401), forbidden (403), outside_coverage (422), rate_limited (429), upstream_error (502), upstream_timeout (504).

GET/v1/realtime

Requires a key with the realtime product.

Live hourly records for one location: pedestrian-level wind speeds, thermal comfort and pollutant concentrations, using the model data within radius metres of the point. Provide either address or both lat and lon. There is no metrics parameter: every record carries all its fields.

The location must fall inside a covered city that has the real-time product (GET /v1/cities?product=realtime lists them). Points outside every covered city receive an instant 422 outside_coverage; points inside a city that lacks real-time receive 422 product_unavailable.

Responses are cached server-side for 5 minutes per (lat, lon, radius) triple; X-Cache reports hit or miss. meta.retrieved_utc is when the response was assembled; the hourly payload itself may be up to 5 minutes older.

Parameters

Response fields

Record fields

Example

{
  "city": { "id": "brussels", "name": "Brussels", "country": "BE" },
  "location": { "address": null, "lat": 50.82068, "lon": 4.35821 },
  "meta": {
    "dataset": "brussels_extended",
    "radius_m": 10,
    "hours": 2,
    "retrieved_utc": "2026-08-20T10:15:42Z"
  },
  "hourly": [
    {
      "hour": "2026-08-20T09:00:00.000Z",
      "timestamp": "1787216400000",
      "c": 18.4, "c_pm25": 6.2, "c_pm10": 11.0, "c_o3": 48.1,
      "ucomfort": 1.2, "ugust": 2.1, "utci": 24.6
    },
    {
      "hour": "2026-08-20T10:00:00.000Z",
      "timestamp": "1787220000000",
      "c": 17.9, "c_pm25": 5.9, "c_pm10": 10.6, "c_o3": 51.3,
      "ucomfort": 1.3, "ugust": 2.4, "utci": 25.2
    }
  ]
}

Errors: validation_error (400), unauthorized (401), forbidden (403), outside_coverage (422), product_unavailable (422), rate_limited (429), upstream_error (502), upstream_timeout (504).

GET/v1/forecast

Requires a key with the forecast product.

Forecast hourly records for one location, out to roughly 48 hours, in exactly the same record shape as GET /v1/realtime. The spacing between records may be irregular; read each record's timestamp rather than assuming a fixed interval.

Parameters, response fields and gating are identical to /v1/realtime: the location must fall inside a covered city that has the forecast product (GET /v1/cities?product=forecast).

Example

{
  "city": { "id": "brussels", "name": "Brussels", "country": "BE" },
  "location": { "address": null, "lat": 50.82068, "lon": 4.35821 },
  "meta": {
    "dataset": "brussels_extended",
    "radius_m": 10,
    "hours": 48,
    "retrieved_utc": "2026-08-20T10:15:42Z"
  },
  "hourly": [
    {
      "hour": "2026-08-20T11:00:00.000Z",
      "timestamp": "1787223600000",
      "c": 16.8, "c_pm25": 5.7, "c_pm10": 10.2, "c_o3": 55.4,
      "ucomfort": 1.5, "ugust": 2.9, "utci": 26.1
    },
    { "...": "..." }
  ]
}

Errors: validation_error (400), unauthorized (401), forbidden (403), outside_coverage (422), product_unavailable (422), rate_limited (429), upstream_error (502), upstream_timeout (504).

POST/v1/reports

Requires a key with the reports product.

Starts asynchronous generation of an Environmental Intelligence Report, HTML plus PDF, for one location. Provide either address or both lat and lon in the JSON body; when only coordinates are given, the address label is resolved by reverse geocoding, falling back to "lat, lon" formatted to 5 decimals.

Any location in Belgium is accepted: inside the Brussels high-resolution zone the report is built from the street-level model, elsewhere from the nationwide dataset. Locations outside every covered area receive an instant 422 outside_coverage without any work starting. Each accepted request counts against the key's daily report quota, checked before any work starts. Poll GET /v1/reports/{job_id} for progress; generated files are retained for 30 days.

Request body

Example request

{
  "address": "Chaussée de Waterloo 481, 1050 Ixelles",
  "lang": "en"
}

Response, 202 Accepted

{
  "job_id": "3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d",
  "status": "processing",
  "stage": "queued",
  "links": {
    "status": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d"
  }
}

Errors: validation_error (400), unauthorized (401), forbidden (403), outside_coverage (422), rate_limited (429), quota_exceeded (429), upstream_error (502), upstream_timeout (504).

GET/v1/reports/{job_id}

Requires a key with the reports product.

The current state of a report job. While it runs, status is processing with stage queued, running or delivering. When the report is ready, status is completed with download links for the HTML and PDF files. A permanently failed job returns status: failed with a detail.

The PDF is rendered on the first status poll after the HTML is ready. If that rendering is still pending, the response is completed with pdf_pending: true and no files.pdf; poll again to retry.

Parameters

Response fields

Example, completed

{
  "job_id": "3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d",
  "status": "completed",
  "address": "Chaussée de Waterloo 481, 1050 Ixelles",
  "lang": "en",
  "files": {
    "html": { "url": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=html" },
    "pdf":  { "url": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=pdf" }
  },
  "expires_in_days": 30
}

Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), rate_limited (429), upstream_error (502), upstream_timeout (504).

GET/v1/reports/{job_id}/download

Requires a key with the reports product.

Streams a generated report in the requested format. The response is sent as an attachment named CLARA_Report_{slug}.html or CLARA_Report_{slug}.pdf, where the slug is derived from the report address. Returns 404 when the file does not exist: unknown job, not yet generated, or expired after 30 days.

Parameters

Example

curl -sS -OJ "https://api.clara.city/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=pdf" \
  -H "Authorization: Bearer YOUR_CLARA_KEY"

The -OJ flags save the file under the name from the Content-Disposition header. The HTML variant is a self-contained page; the PDF is an A4 document.

Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), rate_limited (429).

GET/v1/map/{city}

Requires a key with the map product.

The map catalog: every timestamp currently available for the city, each with a signed TileJSON URL per layer. This is the only map URL a client hardcodes; everything else is discovered from the response, already signed. How to colour those layers is a separate question, answered by GET /v1/scales, which lists what each layer can be plotted as and the scales that colour it. The full integration walkthrough is the city map guide.

The catalog is assembled on demand, so it always reflects what is actually servable, and it is cached server-side for 60 seconds. If the upstream model service is unavailable, the last known-good catalog is served with X-Cache: stale and freshly re-signed URLs.

Parameters

Response fields

Example

{
  "city": { "id": "ravenna", "name": "Ravenna", "country": "IT" },
  "meta": {
    "crs": "EPSG:3857",
    "tile_format": "mvt",
    "generated_utc": "2026-08-19T10:43:53Z",
    "catalog_ttl_s": 60,
    "url_expires_utc": "2026-08-20T11:00:00Z"
  },
  "static": {
    "buildings": { "tilejson": "https://api.clara.city/v1/map/ravenna/tiles/buildings.json?exp=...&sig=..." }
  },
  "live": {
    "timestamp": "2026-08-19T10:00:00Z",
    "timestamp_ms": 1787133600000,
    "layers": {
      "thermal": { "tilejson": "..." },
      "wind":    { "tilejson": "..." }
    }
  },
  "forecast": [
    { "timestamp": "2026-08-19T12:00:00Z", "timestamp_ms": 1787140800000, "layers": { "thermal": { "tilejson": "..." }, "wind": { "tilejson": "..." } } }
  ]
}

Errors: unauthorized (401), forbidden (403), not_found (404), rate_limited (429), upstream_unavailable (503).

Tile endpoints

TileJSON documents and vector tiles are fetched by your map library, not by your code, from the signed URLs the catalog hands out. They carry their authorisation in the query string (exp plus sig), stamped by the catalog: never construct or modify one. Listed here for completeness:

{layer} is thermal, wind or air; {timestamp} is the epoch milliseconds value from the catalog's timestamp_ms. An empty tile answers 204 No Content, which is not an error. An expired or invalid signature answers 401 with code: url_expired; re-fetch the catalog for fresh URLs.

Source-layer names and feature properties per layer, plus working map code, are in the city map guide. The machine-readable contract is the Maps API OpenAPI specification.

Headers

Error codes

Every error is an RFC 9457 problem document with a machine-readable code to branch on, and its type URI links to the matching entry of the error reference:

{
  "type": "https://www.clara.city/docs/errors#outside_coverage",
  "code": "outside_coverage",
  "title": "Outside coverage area",
  "status": 422,
  "detail": "this location is outside the CLARA service area",
  "request_id": "7c1f4c2a-0f3e-4d2b-9a6e-5b8d0c1e2f3a"
}

One rule keeps them easy to reason about: a 403 is always about your key, a 404 or 422 is always about the data.

Each code's full entry, with what to do about it, is in the error reference.