In-Depth Daily

A synchronous endpoint used to calculate weather and NatCat risk probabilities for events, considering each day independently and returning an expected view across all days.

Request

POST /v1/in-depth/daily

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	Perils to evaluate. See Perils Reference.
`events`	`list[Event]`	Yes	Events to evaluate.

Event object

Field	Type	Required	Default	Description
`index`	`integer`	No	Auto-assigned from 0	Unique identifier for the event.
`tag`	`string`	No	`null`	Label for the risk.
`location`	`string`	Conditional	—	Location name, e.g. `"Los Angeles USA"`. Required if `latitude`/`longitude` not provided.
`latitude`	`float`	Conditional	—	Latitude. Required with `longitude` if `location` not provided.
`longitude`	`float`	Conditional	—	Longitude. Required with `latitude` if `location` not provided.
`start_date`	`string`	No	Today (GMT, BST)	Start date in `YYYY-MM-DD` format.
`end_date`	`string`	No	Today (GMT, BST)	End date in `YYYY-MM-DD` format. Must be ≥ `start_date`.
`start_hour`	`integer`	No	`0`	Start hour of day (0–23).
`end_hour`	`integer`	No	`23`	End hour of day (0–23). Must be ≥ `start_hour`.

Note: When using hours the interval from start_hour:00 to end_hour:59 is evaluated.

Response

Success (200) or Multi-Status (207)

200 means all requested work succeeded. 207 means one or more event/peril items failed and details are available in failed_items; successful results are still returned normally in results.

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

Result object

Field	Type	Description
`index`	`integer`	Event index.
`peril`	`string`	Peril name.
`latitude`	`float`	Resolved latitude.
`longitude`	`float`	Resolved longitude.
`threshold`	`list[float\\|string]`	All available threshold values for the peril.
`probability`	`list[float]`	Exceedance probability at each threshold.
`return_period`	`list[float]`	Exceedance probability at each threshold, expressed as a return period
`unit`	`string`	Unit of the thresholds.

Metadata object

Field	Type	Description
`total_requested`	`integer`	Number of events in the request.
`successful`	`integer`	Events with at least one successful result.
`failed`	`integer`	Number of failed items.
`event_outcomes`	`EventOutcomes`	Explicit event-level outcome counts.
`peril_outcomes`	`PerilOutcomes`	Explicit event-peril outcome counts.

event_outcomes separates fully successful, partially successful, and failed events. Its requested count always equals successful + partially_successful + failed.

peril_outcomes treats each unique event-peril pair as one requested outcome. Its requested count always equals successful + failed. One event-level failed_item, such as a geocoding error, can therefore account for several failed peril outcomes.

`event_outcomes` field	Description
`requested`	Number of events in the request.
`successful`	Events for which every requested peril outcome succeeded.
`partially_successful`	Events with both successful and failed peril outcomes.
`failed`	Events with no successful peril outcomes.

`peril_outcomes` field	Description
`requested`	Number of unique event-peril outcomes requested.
`successful`	Requested outcomes represented in `results`.
`failed`	Requested outcomes not represented in `results`.

FailedItem object

Field	Type	Description
`index`	`integer`	Event index that failed.
`stage`	`string`	Processing stage where failure occurred (`geocoding`, `model_execution`).
`error`	`string`	Description of the error.
`peril`	`string\\|null`	Peril that failed, when the failure is peril-specific.
`window_index`	`integer\\|null`	Always `null` for daily responses.

Example

Example Request

curl -X 'POST' \
  'https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/in-depth/daily' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "perils": ["Rain"],
  "events": [
    {
      "index": 0,
      "tag": "London concert",
      "location": "London UK",
      "start_date": "2025-07-01",
      "end_date": "2025-07-03",
      "start_hour": 8,
      "end_hour": 20
    },
    {
      "index": 1,
      "latitude": 40.7128,
      "longitude": -74.006,
      "start_date": "2025-08-15",
      "end_date": "2025-08-15"
    }
  ]
}'

Example response

{
  "results": [
    {
      "index": 0,
      "peril": "Rain",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "threshold": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25],
      "probability": [0.95, 0.82, 0.65, 0.48, 0.33, 0.22, 0.15, 0.10, 0.07, 0.05, 0.03, 0.01, 0.004, 0.001],
      "unit": "mm"
    },
    {
      "index": 1,
      "peril": "Rain",
      "latitude": 40.7128,
      "longitude": -74.006,
      "threshold": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 20, 25],
      "probability": [0.95, 0.82, 0.65, 0.48, 0.34, 0.22, 0.15, 0.10, 0.07, 0.05, 0.02, 0.01, 0.004, 0.001],
      "unit": "mm"
    }
  ],
  "failed_items": [],
  "metadata": {
    "total_requested": 2,
    "successful": 2,
    "failed": 0,
    "event_outcomes": {
      "requested": 2,
      "successful": 2,
      "partially_successful": 0,
      "failed": 0
    },
    "peril_outcomes": {
      "requested": 2,
      "successful": 2,
      "failed": 0
    }
  }
}

Note

This is only an example response and query. The exact response may differ.

Partial failure example (207)

{
  "results": [
    {
      "index": 0,
      "peril": "Rain",
      "latitude": 51.5074,
      "longitude": -0.1278,
      "threshold": [5.0],
      "probability": [0.5],
      "return_period": [2.0],
      "unit": "mm"
    }
  ],
  "failed_items": [
    {
      "index": 0,
      "stage": "model_execution",
      "error": "Peril 'MaxWindGust' failed: model timeout",
      "peril": "MaxWindGust",
      "window_index": null
    }
  ],
  "metadata": {
    "total_requested": 1,
    "successful": 1,
    "failed": 1,
    "event_outcomes": {
      "requested": 1,
      "successful": 0,
      "partially_successful": 1,
      "failed": 0
    },
    "peril_outcomes": {
      "requested": 2,
      "successful": 1,
      "failed": 1
    }
  }
}

Limits

Maximum 25 peril-event combinations per request (e.g. 5 perils x 5 events).
end_date must be on or after start_date.
end_hour must be >= start_hour.

Errors

Status	Description
401	Missing or invalid API key.
207	One or more event/peril items failed; see `failed_items`.
422	Validation error (invalid perils, dates, or exceeding limits).