Forecast API

The Forecast API provides programmatic access to the engine's calibrated probability output — the same data that powers the dashboard.

API specifications are preliminary and subject to change during development. This documentation represents the planned API design.

Get Forecast

GET /v1/forecast

Retrieves calibrated probability forecasts for a location and variable.

Parameters

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude (-90 to 90)
`lon`	float	Yes	Longitude (-180 to 180)
`variable`	string	Yes	Weather variable: `temperature_max`, `temperature_min`, `rainfall`, `irradiance_ghi`, `wind_speed`
`threshold`	float	Yes	Event threshold (e.g., 35 for temperature > 35°C)
`unit`	string	No	Unit: `celsius` (default), `fahrenheit`, `mm`, `kwh_m2_day`, `ms`
`horizon_days`	int	No	Forecast horizon in days (default: 10, max: 16)
`project_id`	string	No	Project ID for project-specific calibration

Example Request

curl -H "Authorization: Bearer ch_live_xxxxxxxxxxxx" \
  "https://api.cliffhorizon.com/v1/forecast?lat=1.3521&lon=103.8198&variable=temperature_max&threshold=35&unit=celsius&horizon_days=7"

Example Response

{
  "location": {
    "lat": 1.3521,
    "lon": 103.8198,
    "name": "Singapore"
  },
  "variable": "temperature_max",
  "threshold": 35,
  "unit": "celsius",
  "generated_at": "2026-04-04T10:00:00Z",
  "nwp_cycle": "2026-04-04T06:00:00Z",
  "forecasts": [
    {
      "date": "2026-04-05",
      "lead_days": 1,
      "probability": 0.42,
      "ensemble_spread": 0.08,
      "calibration_confidence": 0.95,
      "point_forecast": 34.2,
      "ensemble_min": 32.1,
      "ensemble_max": 36.8
    },
    {
      "date": "2026-04-06",
      "lead_days": 2,
      "probability": 0.38,
      "ensemble_spread": 0.12,
      "calibration_confidence": 0.92,
      "point_forecast": 33.8,
      "ensemble_min": 31.5,
      "ensemble_max": 37.1
    }
  ],
  "provenance": {
    "nwp_sources": ["gfs_ensemble_31", "ecmwf_ensemble_51"],
    "satellite_source": "satsure_sparta_lst",
    "bias_correction": "city_season_regime_v2",
    "calibration_curve": "singapore_temperature_d1_q2_2026"
  }
}

Response Fields

Field	Description
`probability`	Calibrated P(variable > threshold) — the engine's core output
`ensemble_spread`	Standard deviation across ensemble members (uncertainty measure)
`calibration_confidence`	Confidence in the calibration curve given training sample size
`point_forecast`	Ensemble mean point forecast (for reference, not the primary output)
`provenance`	Full audit trail — NWP sources, satellite data, correction methodology

Get Multi-Variable Forecast

GET /v1/forecast/multi

Returns calibrated probabilities for multiple variables at the same location — used for integrated risk scoring.

Parameters

Same as single-variable, except variable accepts a comma-separated list:

variable=temperature_max,rainfall,wind_speed

Each variable requires its own threshold parameter, passed as comma-separated values in the same order.

Webhook: Forecast Updates

Subscribe to real-time forecast updates via webhook. See Webhooks for configuration.