API reference

Every CLARA endpoint on one page: parameters, response fields, an abridged example and the errors each one can return. CLARA serves hyper-local air quality, wind comfort and danger, thermal comfort and noise, 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), 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. How to get a key and how origin registration works: 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 first connectivity check.

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 also carries authorized, whether that key is scoped to the city. The response is cacheable for an hour (Cache-Control: public, max-age=3600). Called with a key the lifetime is the same but the caching turns private (Cache-Control: private, max-age=3600, with Vary: Authorization, X-API-Key), because the answer then depends on the key.

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. Where the next expansion of a city has been announced, a second Feature, planned_boundary, gives that coming zone, so a client can draw it alongside the current one. Brussels carries the Capital Region there. Cacheable for an hour; it changes only when coverage changes. Called with a key the caching turns private (Cache-Control: private, max-age=3600, with Vary: Authorization, X-API-Key); the lifetime is unchanged.

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": { "name": "Brussels coverage boundary" },
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[4.31282, 50.87911], [4.31355, 50.87801], "..."]]
    }
  },
  "planned_boundary": {
    "type": "Feature",
    "properties": { "name": "Brussels planned coverage boundary" },
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[4.28247, 50.83785], [4.27765, 50.83785], "..."]]
    }
  }
}

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; thermal as the UTCI stress categories (utci) or as the same reading drawn as a temperature (utci-temp, coloured by thermal-auto by default: Cold, Neutral or Hot chosen for each hour, see below). A scale is how to colour one view. These definitions sit behind every coloured value CLARA renders, published so clients never hardcode them. Cacheable for an hour; a scale changes only when its issuing authority revises it.

Where the scales come from

The Belgian Air Quality Index (BelAQI) provides a comprehensive measure of air quality. It is calculated based on the concentration of several key pollutants: PM2.5, PM10, NO2 and O3. A higher BelAQI value indicates poorer air quality and greater risk for health. The index ranges from 1 (Excellent) to 10 (Horrible). Learn more

The Wind Comfort Index assesses how comfortable the wind conditions are for outdoor activities. It is based on the City of London microclimatic guidelines, which provide a comfort rating for different activities from 1 (comfortable for all activities) to 5 (dangerous for all activities). Learn more

The Universal Thermal Climate Index (UTCI) is an international standard for assessing thermal comfort in outdoor environments. It considers air temperature, wind speed, humidity, and radiation to provide a comprehensive measure of how the environment feels to the human body. The index ranges from extreme cold stress to extreme heat stress. Learn more

Every scale served by this endpoint carries its source as reference, so a legend can link its own provenance without hardcoding a URL.

Parameters

Response fields

Example

GET /v1/scales?metric=wind

{
  "views": [
    { "id": "comfort-danger", "metric": "wind", "name": "Wind comfort and danger",
      "fields": ["Ucomfort", "Ugust"],
      "field_labels": { "Ucomfort": "Wind", "Ugust": "Gust" },
      "scales": ["wind-comfort-standard", "wind-comfort-colour-blind"],
      "default_scale": "wind-comfort-standard", "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-comfort-standard", "view": "comfort-danger", "kind": "classes",
      "name": "Standard", "default": true },
    { "id": "wind-comfort-colour-blind", "view": "comfort-danger", "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

GET /v1/scales/air-belaqi

{
  "id": "air-belaqi",
  "metric": "air",
  "view": "index",
  "name": "BelAQI air quality index",
  "authority": "IRCEL-CELINE (Belgium)",
  "description": "Belgian air quality index, 1 (Excellent) to 10 (Horrible). ...",
  "kind": "classes",
  "fields": ["C", "C_PM25", "C_PM10"],
  "default": true,
  "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":  { "field": "C", "bounds": [10, 15, 20, 30, 40, 45, 50, 60, 75],
              "zero_means_missing": true },
    "pm25": { "field": "C_PM25", "bounds": [3.5, 7.5, 10, 15, 20, 35, 50, 60, 75] },
    "pm10": { "field": "C_PM10", "bounds": [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, all four scope axes, and limits. The first call to make after receiving a key: it confirms the key works and shows exactly what it can reach.

Response fields

Example

{
  "label": "your-company",
  "type": "sk",
  "cities": ["brussels"],
  "products": ["geocode", "historical", "realtime", "forecast", "reports"],
  "metrics": ["air", "wind", "thermal"],
  "horizons": ["realtime", "forecast"],
  "coverage": ["*"],
  "limits": { "rate_per_min": 100, "reports_per_day": 100 },
  "origins": [],
  "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. Coordinates are returned only for candidates inside the CLARA service area, a covered city or Belgium; a candidate outside it comes back as its label with covered: false and nothing else. covered is graded, and means exactly "we have data there": high_res inside a city's current zone, high_res_in_development inside an announced expansion (the Brussels Capital Region), national_low_res elsewhere in Belgium, false beyond. 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,
      "point": "address",
      "relevance": 1.0,
      "covered": "high_res",
      "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, thermal comfort and noise, 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 6 decimals before processing.

Any location in Belgium is served. Every address in the Brussels Capital Region gets high-resolution data (brussels_extended or brussels_region), and the rest of Belgium is answered by the 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, the nearest outdoor 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

Hours window

With hours, the answer says which window it used in meta.hours_window (for example "08-20") and how many hours in meta.hours. A day count, such as hot days, counts a day when one of its window hours crosses the threshold; a window across midnight belongs to the day it starts on. Figures that need the fixed day and night split or a whole night (day_good_pct, night_good_pct, tropical_nights, the summer-night comparison) are null or left out when the window does not include them, and so is the city-centre air benchmark. Each location and window is computed once; the first request for a new window takes as long as a new location.

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.

Response fields, noise

Yearly noise from road traffic, rail and aircraft, read at the location by the same rule as the other pillars. Served in the Brussels-Capital Region; elsewhere the block is omitted and meta.metrics does not list it. It is a yearly figure, so hours does not change it. The score follows the total day-evening-night level of all sources together, on Brussels Environment's 2021 noise classes: very calm below 50 dB scores 7.5 or more, calm (50 to 60 dB) 6.5 to 7.5, noisy (60 to 70 dB) 5 to 6.5, very noisy (70 dB and above) below 5. A health block adds the share of residents who could be highly annoyed or highly sleep disturbed at this outdoor level, from the European dose-response curves (Directive (EU) 2020/367).

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_key_coverage (403), location_unavailable (403), outside_coverage (422), rate_limited (429), upstream_error (502), upstream_timeout (504).

GET/v1/historical/areas/{city}

Requires a key with the historical product, scoped to the city.

The same reference-year ratings as /v1/historical/stats, worked out for whole areas instead of one address. For Brussels the areas are the 19 communes, identified by their INS code, plus the whole region. Add the area id to the path to get just one: /v1/historical/areas/brussels/21009 for Ixelles, or /v1/historical/areas/brussels/region.

Each area gets a figure per pillar and per period: the full year, the four seasons (spring March to May, summer June to August, autumn September to November, winter December to February) and the twelve months (jan to dec). Pillars follow your key: a key holding only wind sees only wind.

The figures are computed in advance, so answers are instant. The hours parameter works as on /v1/historical/stats, so an address and its area can be compared over the same hours. The first request for a new window is computed on demand and can take up to a minute; after that it answers instantly. A city with no area statistics yet answers 404 not_found.

Two scopes per area

stats.all covers the whole area, every part weighted by the surface it covers. stats.highres carries the same figures and highres_share_pct is 100: area statistics are high resolution across the whole Brussels Capital Region, in the current high_res zone and in the part still in development alike.

Keys limited to the high-resolution zone

A key with coverage: ["high_res"] sees only the areas inside the current high-resolution zone, the part of the Region where GET /v1/geocode answers covered: high_res. Each area is taken as its part inside the zone, with figures computed on that part alone: the communes at least 80% inside it (today Etterbeek, Ixelles, Saint-Gilles and Saint-Josse-ten-Noode), the centre of the City of Brussels (21004-centre: the City of Brussels without Laeken), and the zone itself as region. share_of_parent_pct says how much of the commune that part covers; 21004-centre also carries kind: "part" and its parent commune. meta.coverage reads high_res. Any other area id answers 404 not_found.

Parameters

Response fields

The figures

Values

Without hours, air and wind use every hour and thermal the daytime hours, 08:00 to 20:00 local; with it, all three use the window. The thermal year is the weakest of summer, spring and autumn, as in the point rating. Winter thermal figures are given too, but winter never counts toward the yearly rating.

Noise is a yearly level by day, evening and night, so hours does not change it. Its score is the noise score of /v1/historical/stats, its classes are Brussels Environment's 2021 classes: 1 very calm (below 50 dB), 2 calm (50 to 60 dB), 3 noisy (60 to 70 dB), 4 very noisy (70 dB and above). The seasons and months come from the model's daily levels and differ only a little.

Example

curl -H "Authorization: Bearer $CLARA_KEY" \
  "https://api.clara.city/v1/historical/areas/brussels/21013"

{
  "city": { "id": "brussels", "name": "Brussels", "country": "BE" },
  "meta": {
    "dataset": "brussels_extended",
    "reference_year": 2025,
    "area_kind": "commune",
    "metrics": ["air", "wind", "thermal"],
    "...": "..."
  },
  "area": {
    "id": "21013",
    "name": "Saint-Gilles - Sint-Gillis",
    "area_km2": 2.53,
    "highres_share_pct": 100.0,
    "stats": {
      "all": {
        "thermal": {
          "year": {
            "average": 5.8,
            "worst": 3.2,
            "values": {
              "heat_stress_hours": { "average": 133.7, "top": "...", "bottom": "..." },
              "hot_days": { "average": 30.4, "top": "...", "bottom": "..." },
              "...": "..."
            },
            "rated_km2": 2.53,
            "...": "..."
          },
          "...": "..."
        },
        "...": "..."
      },
      "highres": { "...": "..." }
    }
  }
}

Errors: unauthorized (401), forbidden (403), not_found (404), product_unavailable (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.

In Brussels the whole Brussels Capital Region is served: meta.dataset is brussels_extended inside the high-resolution zone (boundary at GET /v1/cities/brussels) and brussels_region in the rest of the Region. A key limited to the high-resolution zone receives 403 outside_key_coverage outside it.

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_key_coverage (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_key_coverage (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.

The address printed on the report is in the report's language. Brussels streets and municipalities have a French and a Dutch name: a Dutch report shows the Dutch address only, French and English reports the French one, whichever form the request used.

Every report is built in English, French and Dutch from the same analysis, each version with the address in its own language. lang picks the language of files in the job status; the other two come in translations. It is still one job and one unit of quota.

Any location in Belgium is accepted. Anywhere in the Brussels Capital Region the report is built from high-resolution data, and elsewhere in Belgium 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_key_coverage (403), location_unavailable (403), outside_coverage (422), rate_limited (429), quota_exceeded (429), upstream_error (502), upstream_timeout (504).

GET/v1/reports/address

Requires a key with the reports product.

The address a report would print for the same address, lat, lon and lang, without creating the report and without using report quota. Use it to name the report before it exists, for example on a payment page. The answer is {"address": "Lakenweversstraat 2, 1050 Elsene", "lang": "nl"}: in the report's language, like the report itself. Where no report can be made (a city without reports, a city outside your key's scope, a point outside Belgium and every city, a location that is unavailable), it answers the same error POST /v1/reports would, so you can check before anyone pays.

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" }
  },
  "translations": {
    "fr": {
      "address": "Chaussée de Waterloo 481, 1050 Ixelles",
      "files": {
        "html": { "url": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=html&lang=fr" },
        "pdf":  { "url": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=pdf&lang=fr" }
      }
    },
    "nl": {
      "address": "Waterlosesteenweg 481, 1050 Elsene",
      "files": {
        "html": { "url": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=html&lang=nl" },
        "pdf":  { "url": "/v1/reports/3f8a2c1e-9b4d-4e6a-8c2f-1d5e7a9b0c3d/download?format=pdf&lang=nl" }
      }
    }
  },
  "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), upstream_unavailable (503, another language still being prepared: retry after the Retry-After seconds).

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. Colouring is a separate question, answered by GET /v1/scales: 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

The two time blocks follow the key's horizon scope. A key without realtime gets a catalog with no realtime block; a key without forecast gets an empty forecast array. Neither is an error, and neither means the city lacks the data. Check the scope with GET /v1/key.

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=..." }
  },
  "realtime": {
    "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. A URL whose exp has passed answers 401 with code: url_expired; re-fetch the catalog for fresh URLs. A URL that is unsigned, or whose signature does not check out, answers 401 with code: unauthorized instead.

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: a 403 is always about your key, a 404 or 422 always about the data.

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