Core concepts
At BirdsEyeView we have some specific languge for the endpoints.. Here are the definitions explained
Perils
A peril is a modelled hazard: Rain, MaxWindGust, Wildfire, Earthquake, TropicalCyclone and so on. Each peril has an API name, a default unit and a set of thresholds. Your key determines which perils you can query; the full catalogue is in the perils reference, and the modelling methodology behind each peril is documented in the CERA® Hazard Guide.
Events
An event is a location plus a time window: "this address, these dates, these hours". Locations can be given as a place-name string (we geocode it) or as latitude/longitude. Coordinates win for precision on schedule business. Requests are priced and limited in peril-event combinations: 2 perils × 3 events = 6 combinations. For cat underwriting the window is typically the policy year: start_date defaults to tomorrow and end_date to one year ahead, so you can submit a location with only an address and get annual return periods automatically. Set start_date and end_date manually for shorter windows (e.g., construction or contingency underwriting).
The exceedance curve
The core output. For each peril-event combination the API returns three parallel arrays:
threshold: hazard intensities in the peril's unit (e.g. CAT0 to CAT5 for tropical cyclone, or millimetres of rain);probability: the probability the threshold is exceeded within the window;return_period: the same information expressed in years (a 0.01 probability ≈ a 1-in-100-year event).
Because you receive the whole curve rather than a single point, you can apply your own vulnerability functions, deductibles and layer structures downstream, or simply read off the probability at the threshold that matters to you.
Modes: lite, in-depth, batch
| Mode | Output | Best for |
|---|---|---|
| Lite | No peril list needed: every peril on your key runs automatically. A return period in years per peril, with a risk descriptor band (Extreme, Severe, Moderate, Low, Remote, Negligible) | One-call location screening across all CAT perils |
| In-depth | You choose exactly which perils to run, CAT or weather; full exceedance curve for each | Point-of-underwriting hazard, pricing inputs |
| Batch | CSV of curves for a whole schedule, asynchronously | Portfolios, renewal books, exposure sweeps |
Partial success
Multi-event requests do not fail wholesale because one row is bad. Successfully processed items come back in results; anything that failed (geocoding, model execution) is itemised in failed_items with a stage and an error, and the response carries HTTP 207 Multi-Status. Always check metadata.partial_failure before assuming a complete set.