Mould Detect Data API

GETTING STARTEDAuthentication

Every endpoint except GET /health requires an API key, sent in the x-api-key request header. Keys look like wk_live_<32 characters>. There is no OAuth, no bearer token, and no query-string key — only the header.

# every authenticated request carries this header
x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are issued directly to integration partners — request one through your Mould Detect contact. Each key carries a daily request quota; exceeding it returns 429 until the UTC day rolls over. Only a SHA-256 hash of your key is ever stored server-side, so keep the plaintext safe — it cannot be recovered, only re-issued.

GETTING STARTEDConventions

GETTING STARTEDErrors & status codes

Errors use one consistent envelope on every endpoint — a JSON body with error: true and a human-readable reason:

{ "error": true, "reason": "invalid parameter 'latitude': input should be less than or equal to 90" }

Error reasons are safe to surface in logs — they never contain AWS identifiers, internal ARNs, or account IDs.

GETTING STARTEDQuickstart

A two-day Sydney forecast, temperatures + precipitation + weather code:

curl -s -H "x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.molddetect.app/v1/daily?latitude=-33.8688&longitude=151.2093&forecast_days=2&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,weather_code&timezone=auto"

{
  "latitude": -33.8688, "longitude": 151.209,
  "timezone": "Australia/Sydney", "utc_offset_seconds": 36000,
  "model": "gfs", "run": "2026-07-20T06Z",
  "daily": {
    "time":                ["2026-07-20", "2026-07-21"],
    "temperature_2m_max":  [16.1, 18.2],
    "temperature_2m_min":  [12.3, 9.1],
    "precipitation_sum":   [0.0, 0.0],
    "weather_code":        [0, 3]
  },
  "daily_units": { "temperature_2m_max": "°C", "precipitation_sum": "mm", … }
}

ENDPOINTDaily forecast

The core feed: daily aggregates for any point — up to 7 past days, today, and up to 7 forecast days — bucketed to local calendar days. Past days are served from each day's own model run; forecast days (including today) come from the latest run. The top-level run field always reports the latest run id.

Query parameters

Response body

ENDPOINTCurrent conditions

A single lightweight reading for the current moment — the model sample at-or-immediately-before now, plus today's high/low. Built for polling clients like Theme Clock: it is cacheable and supports conditional requests (see Caching).

Query parameters

{
  "timezone": "Australia/Sydney", "model": "gfs",
  "run_id": "2026-07-20T06Z", "sample_time_utc": "2026-07-20T09:00:00+00:00",
  "temperature_2m": 13.7, "relative_humidity_2m": 74.8,
  "wind_speed_10m": 13.2, "wind_gusts_10m": 25.2, "weather_code": 0,
  "temperature_2m_max": 16.1, "temperature_2m_min": 12.3,
  "units": { "temperature_2m": "°C", "wind_speed_10m": "km/h", … }
}

ENDPOINTHistorical daily

Historical daily weather from the ERA5-Land reanalysis archive — including soil-moisture layers the forecast feed doesn't carry. Aggregated to local-time days. Australia region (v1)

Query parameters

Each day also carries a data_completeness fraction (0–1); fully-missing days are omitted from the arrays entirely.

ENDPOINTFlood forecast

River-discharge forecast and flood severity from the Global Flood Awareness System (GloFAS). The requested point is snapped to the nearest real river cell — the highest-upstream-area cell in a 5×5 (±0.1°) window — because a naïve nearest-cell lookup misses rivers. Australia region (v1)

Query parameters

Response body

ENDPOINTAir quality forecast

CAMS global atmospheric-composition forecast — seven pollutants (PM2.5, PM10, O3, NO2, SO2, CO, and an HCHO VOC proxy), three-hourly, up to 5 days ahead. The requested point is snapped to the nearest grid cell on the dataset's native 0.4° grid — no interpolation, same convention as /v1/flood. Every value is banded against the WHO 2021 Air Quality Guideline (see Bands below). Australia region (v1)

Query parameters

Response body

curl -s -H "x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.molddetect.app/v1/air?latitude=-33.8688&longitude=151.2093&days=2"

{
  "location": { "lat": -33.8688, "lon": 151.2093 },
  "model": "cams-global", "run": "2026-08-04T00",
  "units": { "pm2_5": "ug/m3", … },
  "guideline": "who-2021-multiples", "voc_proxy": "hcho",
  "attribution":
    "Generated using Copernicus Atmosphere Monitoring Service information 2026",
  "now": {
    "time": "2026-08-04T09:00Z",
    "pm2_5": { "value": 8.4, "band": "good" },
    "pm10": { "value": 14.2, "band": "good" },
    …
  },
  "hourly": {
    "time": ["2026-08-04T06:00Z", "2026-08-04T09:00Z", …],
    "pm2_5": [7.9, 8.4, …], … 6 more species
  },
  "daily": {
    "date": ["2026-08-04", "2026-08-05"],
    "pm2_5_max": [9.6, 11.1], "pm2_5_mean": [8.1, 9.4], …
  }
}

Bands — WHO-2021-multiples

Each species is banded against its WHO 2021 Air Quality Guideline reference level: good ≤ 1× reference, fair ≤ 2×, poor ≤ 4×, very_poor above 4×. HCHO has no WHO ambient guideline, so it uses a separate, clearly-labelled heuristic instead of a multiple.

ENDPOINTHealth

Liveness plus data freshness — no API key required. Reports the latest run and its age, so you can monitor whether ingest is current. Also serves GET /openapi.json (the machine-readable OpenAPI schema) for codegen and Postman import.

{ "status": "ok", "model": "gfs", "latest_run": "2026-07-20T06Z", "age_seconds": 10800 }

REFERENCEDaily variables

Pass any subset in daily= (comma-separated). Omitting daily returns the full base set. The three opt-in derived variables are only returned when named explicitly.

REFERENCEWeather codes

The weather_code field follows the WMO 4677 convention (the same family Open-Meteo and many clients use). Common values:

REFERENCECaching & conditional requests

All four data endpoints return a Cache-Control header and a strong ETag. To poll cheaply, store the ETag and send it back as If-None-Match: an unchanged resource returns 304 Not Modified with no body and no quota-relevant payload.

# 1) first call returns an ETag header:  ETag: "a1b2c3d4e5f6..."
# 2) poll conditionally — 304 if nothing changed:
curl -s -H "x-api-key: wk_live_…" -H 'If-None-Match: "a1b2c3d4e5f6..."' \
  "…/v1/now?latitude=-33.8688&longitude=151.2093" -o /dev/null -w "%{http_code}\n"

How long should a client cache?

The header above is a floor, not a recommendation — a client can hold data longer based on how often the upstream source actually changes:

TOOLINGTesting with Postman

Postman is the fastest way to explore the API interactively. There are two ways in.

Option A — import the OpenAPI schema (recommended)

The API self-describes at /openapi.json. Postman turns that into a ready collection with every endpoint and parameter pre-filled.

1. In Postman: Import → Link, paste https://api.molddetect.app/openapi.json, and import. Postman generates a collection from the live schema.
2. Open the collection's Variables and set baseUrl to the base URL above.
3. Add the API key once, at the collection level (next section), so every request inherits it.

Option B — a minimal collection by hand

Prefer to hand-roll it? Create a collection, add these two variables, then add one request per endpoint using {{baseUrl}} in the URL.

Set the key once, collection-wide

On the collection's Authorization tab, choose type API Key, with:

Leave each request's auth as Inherit auth from parent and the header is added automatically. Storing the key as a secret variable keeps it out of exported collection files.

A starter collection (paste into a new .json, then Import → File)

{
  "info": { "name": "Weather-API v1",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" },
  "auth": { "type": "apikey", "apikey": [
    { "key": "key",   "value": "x-api-key" },
    { "key": "value", "value": "{{apiKey}}" },
    { "key": "in",    "value": "header" } ] },
  "variable": [
    { "key": "baseUrl", "value": "https://api.molddetect.app" } ],
  "item": [
    { "name": "Daily forecast", "request": { "method": "GET", "url":
      "{{baseUrl}}/v1/daily?latitude=-33.8688&longitude=151.2093&forecast_days=3" } },
    { "name": "Current conditions", "request": { "method": "GET", "url":
      "{{baseUrl}}/v1/now?latitude=-33.8688&longitude=151.2093" } },
    { "name": "Flood forecast", "request": { "method": "GET", "url":
      "{{baseUrl}}/v1/flood?latitude=-27.47&longitude=153.03" } },
    { "name": "Health", "request": { "method": "GET", "url": "{{baseUrl}}/health" } }
  ]
}

TOOLINGClient patterns

There is no SDK to install — it's plain HTTPS/JSON, so any HTTP client works. Three idioms worth adopting:

• Respect the units block. Read units / daily_units from the response rather than hard-coding °C/km/h — a client that flips units=imperial then stays correct automatically.
• Poll /v1/now conditionally. Cache the ETag and send If-None-Match; treat 304 as "no change", which keeps a clock or widget cheap and within quota.
• Cache per grid cell, not per place-name. Every request snaps to a grid cell — forecast 0.25° (≈ 25 km), history 0.1° (≈ 10 km), flood 0.05° (≈ 5 km, snapped to the river network). Round the request coordinates to the endpoint's grid resolution and use that, plus the query params that affect the payload (units, timezone, granularity, variable list), as the cache key. Nearby suburbs and localities then collapse into a single upstream request per TTL window instead of one each.

// JavaScript (fetch) — conditional /v1/now poll
const r = await fetch(`${base}/v1/now?latitude=-33.87&longitude=151.21`, {
  headers: { 'x-api-key': key, ...(etag && { 'If-None-Match': etag }) }
});
if (r.status === 304) return cached;        // unchanged
etag = r.headers.get('ETag');
const data = await r.json();