Skip to content

In-Depth Expanding

A synchronous endpoint used to calculate weather and NatCat risk for an expanding window of event dates. This endpoint is designed for cumulative perils (e.g. cumulative rainfall) where you want to see how probabilities evolve as the observation window grows.

Request

POST /v1/in-depth/expanding

Headers

Header Required Description
X-API-Key Yes Your API key
Content-Type Yes application/json

Body

Field Type Required Description
perils list[string] Yes Cumulative perils to evaluate. See Perils Reference.
events list[Event] Yes Events to evaluate.
window_days integer Yes Number of days before start_date to begin the expanding window. Must be between 0 and 7 (inclusive).

Event object

Same as the Daily endpoint.

Example request

{
  "perils": ["CumulativeRain"],
  "events": [
    {
      "index": 0,
      "location": "Manchester UK",
      "start_date": "2025-07-10",
      "end_date": "2025-07-12"
    }
  ],
  "window_days": 3
}

Response

Success (200)

Field Type Description
results list[Result] One entry per event-window-peril combination.
failed_items list[FailedItem] Events that failed processing.
metadata Metadata Summary of request processing.

Result object

Field Type Description
index integer Event index.
window_index integer Expanding window iteration (0 = narrowest window).
peril string Peril name.
latitude float Resolved latitude.
longitude float Resolved longitude.
threshold list[float\|string] Threshold values.
probability list[float] Exceedance probability at each threshold.
unit string Unit of the thresholds.

The metadata and failed_items objects are the same as the Daily endpoint.

Example response

{
  "results": [
    {
      "index": 0,
      "window_index": 0,
      "peril": "CumulativeRain",
      "latitude": 53.4808,
      "longitude": -2.2426,
      "threshold": [0, 5, 10, 15, 20, 25, 30],
      "probability": [0.99, 0.85, 0.60, 0.35, 0.18, 0.08, 0.03],
      "unit": "mm"
    },
    {
      "index": 0,
      "window_index": 1,
      "peril": "CumulativeRain",
      "latitude": 53.4808,
      "longitude": -2.2426,
      "threshold": [0, 5, 10, 15, 20, 25, 30, 35, 40],
      "probability": [0.99, 0.90, 0.72, 0.50, 0.30, 0.16, 0.08, 0.03, 0.01],
      "unit": "mm"
    }
  ],
  "failed_items": [],
  "metadata": {
    "total_requested": 1,
    "successful": 1,
    "failed": 0,
    "partial_failure": false
  }
}

How the expanding window works

Given start_date, end_date, and window_days:

  1. The window always starts at start_date - window_days.
  2. The first iteration (window_index=0) covers from the window start up to window start + 1 day.
  3. Each subsequent iteration expands the end by one day, until end_date is reached.

This allows you to see how cumulative probabilities change as the observation period grows.

Limits

  • Maximum 10 peril-event combinations per request.
  • window_days must be between 0 and 7 (inclusive).
  • Only cumulative perils are accepted. See Expanding perils for list of available expanding perils

Errors

Status Description
401 Missing or invalid API key.
422 Validation error (invalid perils, dates, window_days, or exceeding limits).