# Weather & Hazards API — global weather forecasts (MET Norway, US NWS), historical weather (ERA5), marine/wave forecasts, geocoding, air quality + pollen (OpenAQ, Open-Meteo CAMS), official weather alerts (MeteoAlarm, NWS), natural disasters (GDACS), earthquakes (USGS) and natural events (NASA EONET)

> premium combined snapshot: current weather + AQ + active alerts + nearby hazards + risk_summary{level,reasons,confidence} for a coordinate
> ReefAPI engine `weather-intel` · 13 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/weather-intel/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /weather-intel/v1/environment_current — 3 credits
premium combined snapshot: current weather + AQ + active alerts + nearby hazards + risk_summary{level,reasons,confidence} for a coordinate

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `units` (enum, optional, default "metric") — Unit system for temperatures, wind speeds and precipitation. [one of: metric, imperial]
- `include` (string, optional) — Comma-separated blocks to include: weather, air_quality, alerts, hazards. Default: all.
- `radius_km` (number, optional, default 300) — Search radius in km around the point for nearby hazards (1..2000).

**Returns:** location{lat,lon,country?}, weather{temperature,feels_like,wind,symbol,…}, air_quality{pollutants,aqi_us,aqi_eu,nearest_station_km} | unavailable-with-reason, alerts{active[],coverage_note}, hazards{events[],…}, risk_summary{level,score,reasons[],confidence}, sources{per-source honesty blocks}, attribution[], disclaimer

**Example request body:**
```json
{
  "lat": 52.52,
  "lon": 13.405
}
```

### POST /weather-intel/v1/forecast — 1 credit
global point forecast (MET Norway, ~9 days): hourly steps + daily aggregates with normalized weather-code, feels-like, sunrise/sunset/moon. Optional source=us_nws returns the US-official National Weather Service forecast for US coordinates (api.weather.gov, public domain)

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `units` (enum, optional, default "metric") — Unit system for temperatures, wind speeds and precipitation. [one of: metric, imperial]
- `hours` (integer, optional, default 24) — Number of forecast steps to return (hourly for ~2.5 days, then 6-hourly to ~day 9 — each step carries its timestamp).
- `days` (integer, optional, default 7) — Number of days (1..10).
- `source` (enum, optional, default "auto") — Forecast source. 'us_nws' returns the US-official NWS gridpoint forecast (US coordinates only); 'met'/'auto' use MET Norway global. [one of: auto, met, us_nws]

**Returns:** current{...}, hourly[]{time,temperature,feels_like,wind,humidity,pressure,cloud,uv,precipitation,symbol{code,condition,intensity}}, daily[]{date,temperature_min/max,precipitation_total,wind_speed_max,symbol,sunrise,sunset,moon}, source{...honesty}, attribution, disclaimer — or us_official{periods[],location,...} + source.name=NWS when source=us_nws

**Example request body:**
```json
{
  "lat": 41.0082,
  "lon": 28.9784,
  "days": 3
}
```

### POST /weather-intel/v1/air_quality — 1 credit
nearest-station air quality (OpenAQ v3): pollutants + computed AQI-US/EAQI-EU + station distance + measurement freshness; honest insufficient_data when no station

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `radius_km` (number, optional, default 10) — Search radius in km around the point for monitoring stations (1..25).

**Returns:** pollutants{pm25,pm10,o3,no2,so2,co:{value,unit,measured_at,age_hours,station,station_distance_km,provider}}, aqi_us{value,category,dominant_pollutant}, aqi_eu{index,category}, nearest_station_km, stations[], stale_readings_skipped, insufficient_data?, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "lat": 51.5072,
  "lon": -0.1276,
  "radius_km": 25
}
```

### POST /weather-intel/v1/alerts — 1 credit
official severe-weather warnings by country/US-state or coordinate: EU MeteoAlarm (39 countries) AND US NWS (api.weather.gov, all 50 states + territories + marine zones, via Webshare). The source is chosen automatically from the location; coverage/coverage_note name exactly which authority answered

**Parameters:**
- `country` (string, optional) — MeteoAlarm member country (EU) — slug or ISO2 — OR a US state/marine code (e.g. CA, TX, NY) which routes to NWS api.weather.gov. Alternative to lat/lon.
- `lat` (number, optional) — Latitude (alternative to country) — resolved to a MeteoAlarm country (EU) or NWS coverage (US).
- `lon` (number, optional) — Longitude (alternative to country).
- `severity_min` (enum, optional) — Minimum awareness color (MeteoAlarm yellow/orange/red). [one of: yellow, orange, red]
- `active_only` (boolean, optional, default true) — Only warnings active NOW (onset<=now<expires). false = full feed.
- `limit` (integer, optional, default 50) — Maximum records to return (1..200).

**Returns:** alert_source{authority,scope}, country{slug,name}? | us_area{code}?, alerts[]{event,severity,urgency,certainty,area,onset,expires,headline,instruction,…}, count, coverage, coverage_note, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "country": "germany",
  "active_only": false
}
```

### POST /weather-intel/v1/hazards_nearby — 1 credit
GDACS multi-hazard events (earthquake/cyclone/flood/volcano/wildfire/drought) within a radius of a coordinate, distance-sorted

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `radius_km` (number, optional, default 500) — Search radius in km around the point for hazard events (1..5000).
- `days` (integer, optional, default 14) — Number of days (1..365).
- `types` (string, optional) — Comma-separated disaster types: earthquake, tropical_cyclone, flood, volcano, wildfire, drought (or GDACS codes EQ/TC/FL/VO/WF/DR). Default: all.
- `min_alert_level` (enum, optional, default "green") — Minimum GDACS alert level to include. [one of: green, orange, red]
- `limit` (integer, optional, default 50) — Maximum records to return (1..200).

**Returns:** events[]{type,name,alert_level,severity,severity_text,distance_km,coordinates,from,to,is_current,country,report_url}, count, window_truncated{per-type honesty when the newest-100 cap was hit}, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "lat": 36.2,
  "lon": 140.5,
  "radius_km": 2000,
  "days": 30
}
```

### POST /weather-intel/v1/disasters — 1 credit
global GDACS disaster events with type/alert-level/date/bbox filters, or a single-event detail via event_id+event_type

**Parameters:**
- `types` (string, optional) — Comma-separated disaster types: earthquake, tropical_cyclone, flood, volcano, wildfire, drought (or GDACS codes EQ/TC/FL/VO/WF/DR). Default: all.
- `min_alert_level` (enum, optional, default "green") — Minimum GDACS alert level to include. [one of: green, orange, red]
- `days` (integer, optional, default 30) — Number of days (1..365).
- `bbox` (string, optional) — Bounding-box filter 'min_lon,min_lat,max_lon,max_lat' applied to event coordinates.
- `country` (string, optional) — Filter by GDACS country name or ISO3 (case-insensitive substring).
- `limit` (integer, optional, default 100) — Maximum records to return (1..300).
- `event_id` (integer, optional) — GDACS event id — returns the single-event detail (use with event_type code, e.g. EQ).
- `event_type` (enum, optional) — GDACS event type code for event_id detail lookups. [one of: EQ, TC, FL, VO, WF, DR]

**Returns:** events[]{type,name,alert_level,severity,country,coordinates,from,to,is_current,report_url}, count, window_truncated, source{...honesty}, attribution, disclaimer — or event{...full GDACS detail} when event_id

**Example request body:**
```json
{
  "days": 30
}
```

### POST /weather-intel/v1/earthquakes — 1 credit
USGS earthquake catalog (earthquake.usgs.gov, public domain): filter by magnitude, radius, time window, depth, and PAGER alert — includes small and medium-magnitude events that disaster aggregators like GDACS omit. Results are distance-sorted around a coordinate. Pass event_id for a single-event detail.

**Parameters:**
- `lat` (number, optional) — Latitude for a radius search (with lon + radius_km).
- `lon` (number, optional) — Longitude for a radius search.
- `radius_km` (number, optional, default 500) — Search radius in km around the point for earthquake epicentres (1..20000).
- `min_magnitude` (number, optional) — Minimum earthquake magnitude (USGS). Omit for the full catalog (includes micro-quakes M<2.5 that GDACS never lists).
- `max_magnitude` (number, optional) — Maximum earthquake magnitude (USGS).
- `days` (integer, optional, default 7) — Number of days (1..365).
- `start` (string, optional) — ISO start time (overrides days), e.g. 2026-06-01.
- `end` (string, optional) — ISO end time.
- `min_depth_km` (number, optional) — Minimum hypocenter depth (km).
- `max_depth_km` (number, optional) — Maximum hypocenter depth (km).
- `order` (enum, optional, default "time") — Sort order for the USGS earthquake catalog. [one of: time, time-asc, magnitude, magnitude-asc]
- `pager_alert` (enum, optional) — Filter to quakes with at least this USGS PAGER impact alert. [one of: green, yellow, orange, red]
- `limit` (integer, optional, default 100) — Maximum records to return (1..1000).
- `event_id` (string, optional) — USGS event id — returns the single-event detail.

**Returns:** earthquakes[]{event_id,magnitude,magnitude_type,place,time,coordinates{lat,lon,depth_km},pager_alert,tsunami,felt_reports,mmi,cdi,significance,status,distance_km?,detail_url}, count, source{...honesty}, attribution, disclaimer — or earthquake{...full detail} when event_id

**Example request body:**
```json
{
  "min_magnitude": 5,
  "days": 30,
  "limit": 20
}
```

### POST /weather-intel/v1/natural_events — 1 credit
NASA EONET natural-event catalog (eonet.gsfc.nasa.gov, NASA open data): wildfires, severe storms, volcanoes, floods, icebergs, dust/haze — a second independent hazard source alongside GDACS. Filter by category, status, and date range; optionally list the full EONET category taxonomy.

**Parameters:**
- `category` (enum, optional) — NASA EONET natural-event category filter. [one of: drought, dustHaze, earthquakes, floods, landslides, manmade, seaLakeIce, severeStorms, snow, tempExtremes, volcanoes, waterColor, wildfires]
- `status` (enum, optional, default "open") — EONET event status: open (ongoing), closed, or all. [one of: open, closed, all]
- `days` (integer, optional, default 60) — Number of days (1..365).
- `bbox` (string, optional) — Bounding-box filter 'min_lon,min_lat,max_lon,max_lat' applied to event coordinates.
- `limit` (integer, optional, default 50) — Maximum records to return (1..200).
- `list_categories` (boolean, optional, default false) — Return the EONET category taxonomy instead of events.

**Returns:** events[]{event_id,title,type,category_ids,is_open,last_observed,coordinates,magnitude_value,sources[],link}, count, categories[]?{id,title} when list_categories, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "status": "open",
  "limit": 20
}
```

### POST /weather-intel/v1/fires — 1 credit
Live wildfire and thermal-anomaly hotspots from NASA FIRMS (firms.modaps.eosdis.nasa.gov, NASA open data): pixel-level VIIRS (375 m) and MODIS (1 km) near-real-time detections — the raw sensor data that disaster aggregators like GDACS and EONET do not include. Query by a coordinate radius or a bounding box; each hotspot includes brightness, Fire Radiative Power (FRP), confidence, day/night flag, and the exact acquisition timestamp.

**Parameters:**
- `lat` (number, optional) — Latitude for a radius search (with lon + radius_km); alternative to bbox.
- `lon` (number, optional) — Longitude for a radius search; alternative to bbox.
- `radius_km` (number, optional, default 100) — Search radius in km around the point for active-fire hotspots (1..1000).
- `bbox` (string, optional) — Bounding box 'min_lon,min_lat,max_lon,max_lat' — alternative to lat/lon/radius_km (FIRMS area query).
- `sensor` (enum, optional, default "viirs_snpp") — Satellite sensor for fire detection. VIIRS (375 m resolution) gives the finest detail; MODIS (1 km) covers the longest historical record. All feeds are near-real-time (NRT) from NASA FIRMS. [one of: viirs_snpp, viirs_noaa20, viirs_noaa21, modis]
- `days` (integer, optional, default 1) — Look-back window in days (1..10) for NRT detections.
- `min_confidence` (enum, optional) — Minimum detection confidence (VIIRS low/nominal/high; MODIS percent mapped to the same bands at 30/80). [one of: low, nominal, high]
- `min_frp` (number, optional) — Minimum Fire Radiative Power in megawatts — filters out the smallest thermal anomalies.
- `limit` (integer, optional, default 200) — Maximum records to return (1..1000).

**Returns:** hotspots[]{latitude,longitude,brightness_kelvin,frp_mw,confidence{raw,label,percent},acquired_at,acq_date,acq_time,satellite,instrument,resolution_m,daynight,distance_km?}, count, area{bbox|center+radius_km}, sensor, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "bbox": "-20,-35,55,20",
  "days": 1,
  "limit": 50
}
```

### POST /weather-intel/v1/geocode — 1 credit
Place name → coordinates (Open-Meteo Geocoding, GeoNames-backed, free/keyless): turns a city/town/region name into the lat/lon every other weather-intel action needs, with country, region (admin1/2), population, timezone and elevation. Pass 'id' (a GeoNames id from a prior result) for the single canonical record instead of a name search.

**Parameters:**
- `name` (string, optional) — Place name to search for (city, town, region) — at least 2 characters. Returns matching locations with coordinates. Pass 'id' instead to look up a specific GeoNames id.
- `id` (integer, optional) — GeoNames id (from a prior search result's 'id') to fetch the single canonical place record. Alternative to 'name'.
- `language` (string, optional, default "en") — Result language (ISO-639-1, e.g. en, de, fr, tr, es). Affects the localized place/country/region names.
- `count` (integer, optional, default 10) — Maximum number of place matches to return (1..100).

**Returns:** results[]{id,name,lat,lon,country,country_code,admin1,admin2,population,elevation_m,timezone,feature_code,postcodes}, count, query, source{...honesty}, attribution, disclaimer — or result{...} for an id lookup; empty results[] (count 0) when nothing matches (honest, no guess)

**Example request body:**
```json
{
  "name": "Istanbul",
  "count": 3
}
```

### POST /weather-intel/v1/historical — 2 credits
Historical weather (Open-Meteo Archive / ERA5 reanalysis, 1940→present, free/keyless) for a coordinate and date range: daily aggregates (min/max temp, precipitation, wind, weather-code, sunrise/sunset) and/or hourly variables. The live forecast actions exclude history — this is the long-record companion. Default daily set is returned when neither 'daily' nor 'hourly' is specified.

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `start_date` (string, required) — Start date (ISO YYYY-MM-DD), 1940-01-01 or later.
- `end_date` (string, required) — End date (ISO YYYY-MM-DD), on/after start_date. ERA5 archive lags the present by ~5 days.
- `units` (enum, optional, default "metric") — Unit system for temperatures, wind speeds and precipitation. [one of: metric, imperial]
- `daily` (string, optional) — Comma-separated DAILY variables (Open-Meteo names), e.g. temperature_2m_max, temperature_2m_min, precipitation_sum, rain_sum, snowfall_sum, weather_code, apparent_temperature_max, wind_speed_10m_max, sunrise, sunset. Default set used if both daily+hourly omitted.
- `hourly` (string, optional) — Comma-separated HOURLY variables (Open-Meteo names), e.g. temperature_2m, relative_humidity_2m, precipitation, wind_speed_10m, pressure_msl, cloud_cover, weather_code. Optional — omit for daily-only.

**Returns:** location{lat,lon,elevation_m}, range{start_date,end_date}, units, daily[]{time,...requested vars + normalized symbol from weather_code}, daily_units{}, hourly[]{time,...}?, hourly_units{}?, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "lat": 41.0082,
  "lon": 28.9784,
  "start_date": "2024-01-01",
  "end_date": "2024-01-07"
}
```

### POST /weather-intel/v1/marine — 1 credit
Marine / ocean-wave forecast (Open-Meteo Marine, free/keyless) for a coordinate: significant wave height, period and direction plus swell and wind-wave components — hourly out to several days, plus daily maxima and the current sea state. On land (no marine grid cell) values are honestly null (never fabricated).

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `units` (enum, optional, default "metric") — Unit system for temperatures, wind speeds and precipitation. [one of: metric, imperial]
- `forecast_days` (integer, optional, default 3) — Number of forecast days for wave data (1..8).
- `hourly` (string, optional) — Comma-separated HOURLY wave variables, e.g. wave_height, wave_direction, wave_period, swell_wave_height, swell_wave_direction, swell_wave_period, wind_wave_height, wind_wave_direction. Default set used if omitted.
- `daily` (string, optional) — Comma-separated DAILY wave variables, e.g. wave_height_max, wave_direction_dominant, wave_period_max, swell_wave_height_max.
- `current` (boolean, optional, default true) — Include the current sea state (wave_height, direction, period, swell, wind-wave).

**Returns:** location{lat,lon}, units, current{time,wave_height,wave_direction,wave_period,swell_wave_height,wind_wave_height}?, hourly[]{time,...}, hourly_units{}, daily[]{time,...}?, daily_units{}?, on_land_note?, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "lat": 54.544,
  "lon": 10.402,
  "forecast_days": 2
}
```

### POST /weather-intel/v1/air_quality_forecast — 1 credit
Air-quality FORECAST + pollen (Open-Meteo Air-Quality, CAMS-backed, free/keyless) for a coordinate: hourly forecast of PM2.5/PM10/O3/NO2/SO2/CO, the European AQI and US AQI, plus European pollen (alder/birch/grass/olive/ragweed/mugwort). Complements the OpenAQ nearest-station `air_quality` (which is measured, current only) with a forward forecast and pollen — and needs NO API key. Pollen is European-domain only; outside Europe it is honestly null.

**Parameters:**
- `lat` (number, required) — Latitude in decimal degrees (WGS84), -90..90.
- `lon` (number, required) — Longitude in decimal degrees (WGS84), -180..180.
- `forecast_days` (integer, optional, default 3) — Number of forecast days for air quality (1..7).
- `hourly` (string, optional) — Comma-separated HOURLY variables, e.g. pm2_5, pm10, ozone, nitrogen_dioxide, sulphur_dioxide, carbon_monoxide, european_aqi, us_aqi, uv_index, alder_pollen, birch_pollen, grass_pollen, olive_pollen, ragweed_pollen, mugwort_pollen. Default set used if omitted.
- `current` (boolean, optional, default true) — Include the current-hour AQ + pollen snapshot.

**Returns:** location{lat,lon}, current{time,pm2_5,pm10,european_aqi,us_aqi,...pollen}?, hourly[]{time,...}, hourly_units{}, pollen_note, source{...honesty}, attribution, disclaimer

**Example request body:**
```json
{
  "lat": 52.52,
  "lon": 13.405,
  "forecast_days": 2
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=weather-intel
- Human docs page: https://reefapi.com/docs/weather-intel
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt