Quickstart

From zero to your first hazard curve in five minutes.

1. Get an API key

   Email admin@birdseyeview.ai and we will issue a key scoped to the perils and endpoints in your licence. Keys are passed in the X-API-Key header on every request and expire after one year.

2. Check the service is up

   The health endpoint needs no authentication:

   curl "https://prod-external-weather-api.birdseyeviewtechnologies.com/health"
   # → {"message": "API is running"}
   

3. See which perils your key can access

   curl -H "X-API-Key: YOUR_API_KEY" \
     "https://prod-external-weather-api.birdseyeviewtechnologies.com/v1/perils"
   

4. Request your first hazard curve

   One location, two perils, one POST. No dates are needed: they default to a 12-month policy window starting tomorrow.

   cURLPython RequestJavaScript

   curl -X POST \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "perils": ["TropicalCyclone", "Wildfire"],
       "events": [{
         "location": "Naples, Florida US"
       }]
     }' \
     "https://prod-external-weather-api.birdseyeviewtechnologies.com/v2/in-depth"
   

   import httpx
   
   BASE = "https://prod-external-weather-api.birdseyeviewtechnologies.com"
   headers = {"X-API-Key": "YOUR_API_KEY"}
   
   payload = {
       "perils": ["TropicalCyclone", "Wildfire"],
       "events": [{
           "location": "Naples, Florida US",
           # start_date / end_date default to tomorrow -> one year ahead
       }],
   }
   
   r = httpx.post(f"{BASE}/v1/in-depth", json=payload, headers=headers)
   r.raise_for_status()
   print(r.json())
   

   const BASE = "https://prod-external-weather-api.birdseyeviewtechnologies.com";
   
   const res = await fetch(`${BASE}/v1/in-depth`, {
     method: "POST",
     headers: {
       "X-API-Key": "YOUR_API_KEY",
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       perils: ["TropicalCyclone", "Wildfire"],
       events: [{ location: "Naples, Florida US" }], // dates default to tomorrow -> +1 year
     }),
   });
   const data = await res.json();
   

5. Read the curve

   Each result pairs thresholds with exceedance probabilities. Here Naples shows a 24% chance of at least CAT1 tropical cyclone conditions within the policy year:

   {
     "results": [{
       "index": 0,
       "peril": "TropicalCyclone",
       "latitude": 26.142, "longitude": -81.7948,
       "threshold":   ["CAT0", "CAT1", "CAT2", "CAT3", "CAT4", "CAT5"],
       "probability": [0.42, 0.24, 0.12, 0.05, 0.02, 0.006],
       "return_period": [2, 4, 8, 20, 50, 167],
       "unit": "Saffir-Simpson"
     }],
     "failed_items": [],
     "metadata": { "total_requested": 2, "successful": 2, "failed": 0, "partial_failure": false }
   }
   

That's it. Next, read the core concepts, or head to the API explorer to try other endpoints without writing code.