Historic events

Query the observed record of hail, wildfire, tropical cyclone and tornado events near a location, and retrieve their footprints as GeoJSON for mapping.

What it looks like

Screenshot to follow

Refreshed screenshots of the historical event layers on the CERA® map (current branding) are in preparation and will be inserted here. These endpoints serve the same footprints as GeoJSON; the embedded map renders them for you.

List events

GET /v1/historic-events/{peril_name}/events

Parameter	In	Type	Required	Notes
`peril_name`	path	string	REQUIRED	`Hail`, `Wildfire`, `TropicalCyclone`, `Tornado` (Same name as in-depth mode perils reference). A path variable
`lat`, `lon`	query	float	REQUIRED	Location coordinates
`start_year`, `end_year`	query	integer	OPTIONAL	Year range filter

Example

cURLResponse

curl -X 'GET' -H "X-API-Key: YOUR_API_KEY" \
  "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/historic-events/TropicalCyclone/events?lat=33&lon=-85&start_year=2020&end_year=2020"

[
  {
    "properties": {
      "name": "SALLY",
      "size": 48.87218,
      "tcid": "2020256N25281",
      "season": 2020
    },
    "external_id": "2020256N25281"
  }
]

Get shapes (GeoJSON)

POST /v1/historic-events/{peril_name}/shapes

Returns a GeoJSON FeatureCollection of event footprints for mapping, filtered by radius, size and year range. Set ?include_visual_data=true to receive ready-made styling properties (stroke, fill, fill_opacity, marker_size, z_index and friends).

Body field	Type	Required	Notes
`peril_name`	string	REQUIRED	`Hail`, `Wildfire`, `TropicalCyclone`, `Tornado` (Same name as in-depth mode perils reference). A path variable
`lat`, `lon`	float	CONDITIONAL	Centre of the search
`radius`	`FilterParam`	OPTIONAL	`{"value": 50, "unit": "km"}`; default unit km
`size`	`FilterParam`	OPTIONAL	Event magnitude filter; unit depends on peril (see below)
`start_year`, `end_year`	integer	CONDITIONAL	Year range
`months`	Integer array	OPTIONAL	A list of months to filter for when when the event occured. [6,7] will give events that occured in June and July
`external_id`	string	CONDITIONAL	Event ID from the listing call

Example

Get shape by location queryLocation ResponseGet shape by IDID Response

curl -X 'POST' -H "X-API-Key: YOUR_API_KEY" \
  "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/historic-events/Wildfire/shapes?include_visual_data=true"
-d '{
  "lat":34.04128062212257,
  "lon":-118.22662353515625,
  "radius":{"value":50,"unit":"km"},
  "size":{"value":20,"unit":"acres"},
  "start_year":2016, "end_year":2025
}'

  {"type":"FeatureCollection","features":[
    {"type":"Feature","geometry":{"type":"MultiPolygon","coordinates":[[[[-118.572662832,34.089891449],..,[-118.568207,34.047582999]]]]},"properties":{"data":{"entity_id":"7590e1df-aad0-4e80-9bbb-a943aa6aed24","entity_type":"Wildfire","external_id":"73730f90-5d60-4850-98c2-2431c4284cd7","name":"PALISADES","entity_properties":{"size":94.89,"fire_ID":"73730f90-5d60-4850-98c2-2431c4284cd7","duration":24,"end_date":"2025-01-31","perimeter":140.23,"start_date":"2025-01-07"},"geometry_id":"1b89f2e5-6831-49f9-8b33-7eee19ba0666","geometry_properties":{"created_by":"preprocess_shapefile"}},"visual":{"stroke":"#ff0000","stroke_opacity":0.8,"stroke_width":1.0,"fill":"#ff0000","fill_opacity":0.5,"fill_opacity_on_hover":0.9}}},
    {"type":"Feature","geometry":{"type":"MultiPolygon","coordinates":[[[[-118.081403,34.236285999],...,[-118.159855,34.192195]]]]},"properties":{"data":{"entity_id":"239ae3c4-66b5-40b8-97d6-abfbec768539","entity_type":"Wildfire","external_id":"d8dcb0e7-0ad6-46a4-901a-86d777bb09af","name":"EATON","entity_properties":{"size":56.88,"fire_ID":"d8dcb0e7-0ad6-46a4-901a-86d777bb09af","duration":23,"end_date":"2025-01-31","perimeter":104.93,"start_date":"2025-01-08"},"geometry_id":"cff2b431-94ad-4768-806a-93c0c263ebb0","geometry_properties":{"created_by":"preprocess_shapefile"}},"visual":{"stroke":"#ff0000","stroke_opacity":0.8,"stroke_width":1.0,"fill":"#ff0000","fill_opacity":0.5,"fill_opacity_on_hover":0.9}}}]
  }

This GeoJSON response has been compressed to be visible as an example

curl -X 'POST' -H "X-API-Key: YOUR_API_KEY" \
  "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/historic-events/TropicalCyclone/shapes?include_visual_data=true"
-d '{
  "external_id": "2020256N25281"
}'

  {"type":"FeatureCollection","features":[
    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-88.515855,28.999998],[-88.515129,29.002378],...,[-88.463079,28.778056],[-88.515855,28.999998]]]},"properties":{"data":{"entity_type":"TropicalCyclone","properties":{"name":"SALLY","size":48.87218,"tcid":"2020256N25281","season":2020},"geom_properties":{"value":10.0}},"visual":{"stroke":"#6EC1EA","stroke_opacity":0.66,"stroke_width":1.0,"fill":"#6EC1EA","fill_opacity":0.6,"fill_opacity_on_hover":0.95,"z_index":1}}},
    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-88.515855,28.999998],[-88.433017,29.300054],...,[-88.312773,28.559562],[-88.515855,28.999998]]]},"properties":{"data":{"entity_type":"TropicalCyclone","properties":{"name":"SALLY","size":48.87218,"tcid":"2020256N25281","season":2020},"geom_properties":{"value":15.0}},"visual":{"stroke":"#6EC1EA","stroke_opacity":0.66,"stroke_width":1.0,"fill":"#6EC1EA","fill_opacity":0.6,"fill_opacity_on_hover":0.95,"z_index":1}}},
    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-89.75438,30.015868],[-89.753588,30.018141],,...,[-89.753542,30.013549],[-89.75438,30.015868]]]},"properties":{"data":{"entity_type":"TropicalCyclone","properties":{"name":"SALLY","size":48.87218,"tcid":"2020256N25281","season":2020},"geom_properties":{"value":17.0}},"visual":{"stroke":"#6EC1EA","stroke_opacity":0.66,"stroke_width":1.0,"fill":"#6EC1EA","fill_opacity":0.6,"fill_opacity_on_hover":0.95,"z_index":1}}},
    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-88.934104,29.000001],[-88.625148,28.316172],...,[-88.627329,28.317173],[-88.628604,28.319203]]]},"properties":{"data":{"entity_type":"TropicalCyclone","properties":{"name":"SALLY","size":48.87218,"tcid":"2020256N25281","season":2020},"geom_properties":{"value":26.0}},"visual":{"stroke":"#4DFFFF","stroke_opacity":0.66,"stroke_width":1.0,"fill":"#4DFFFF","fill_opacity":0.6,"fill_opacity_on_hover":0.95,"z_index":1}}},
    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-88.765472,29.297636],[-87.698851,28.188848],...,[-88.765472,29.002292],[-88.765472,29.297636]]]},"properties":{"data":{"entity_type":"TropicalCyclone","properties":{"name":"SALLY","size":48.87218,"tcid":"2020256N25281","season":2020},"geom_properties":{"value":33.0}},"visual":{"stroke":"#FFFFD9","stroke_opacity":0.66,"stroke_width":1.0,"fill":"#FFFFD9","fill_opacity":0.6,"fill_opacity_on_hover":0.95,"z_index":1}}},
    {"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-88.325515,29.795548],[-88.328367,29.787904],...,[-88.326762,29.7923],[-88.325515,29.795548]]]},"properties":{"data":{"entity_type":"TropicalCyclone","properties":{"name":"SALLY","size":48.87218,"tcid":"2020256N25281","season":2020},"geom_properties":{"value":43.0}},"visual":{"stroke":"#FFD98C","stroke_opacity":0.66,"stroke_width":1.0,"fill":"#FFD98C","fill_opacity":0.6,"fill_opacity_on_hover":0.95,"z_index":1}}}]
  }

This GeoJSON response has been compressed to be visible as an example

When to use Events vs Shapes endpoint

The design choice for two endpoints was decided to deal with events where there is long history of large overlapping events. Tropical cyclones for example in North America there are many years (Going back pre-1950) of tropical cyclones and due to their nature will have distinct yet mostly overlapping trajectories and for tropical cyclones we display the full radial impact, and Tropical cyclones are known to be large (Hurricane Katrina's diameter of max wind peaked at 70 miles!). The same applies to earthquakes where they have a large radial extent of feel, similar origins and many years of events.

The workflow for these overlapping events it's better to split out a call by listing all the events and then for each event querying the id to get the shape outline. Querying the shapes all in one leads to multiple overlapping shapes.

Wildfire, Hail and Tornadoes you can also directly call the events output if you want a simply list of events for an area.

What "size" means per peril

Peril	Size meaning	Units
Hail	Hailstone diameter	cm, inch, mm
Fire	Burnt area	km², acre, hectare, sqft, sqmi
Tropical Cyclone	Peak wind speed	m/s
Tornado	EF scale	EF scale

Errors

Status	Meaning
`401`	Missing or invalid API key, or API key not permitted for endpoint
`422`	Unprocessable Content
`500`	Failed to retrieve historic events / shapes