Free alerts API
Read TerraAvert's alerts from your own site, app or feed reader. It is free, needs no key or sign-up, and every alert says who issued it and how it was measured. It is read-only.
Quick start
Open alerts within 300 km of Dubai:
curl -A "Mozilla/5.0" "https://terraavert.com/api/alerts?near=25.2,55.3&radius_km=300&status=open"Send a normal User-Agent header. Our network protection turns away requests that do not identify their client (for example the bare default of some scripting libraries) with a 403.
Endpoints
| Address | What you get |
|---|---|
/api/alerts | Alerts as JSON, oldest first. |
/api/alerts.geojson | The same alerts as a GeoJSON FeatureCollection of points, ready for any map. Alerts without coordinates are left out. |
/api/alerts.atom | An Atom feed of the alerts that are open now, newest first, with each alert's position as GeoRSS. Subscribe to it in a feed reader. |
/api/alerts/{id} | One alert with its history, its permanent-record entry and any outside timestamp covering it. |
/api/predict/location?lat=&lon= | Current flood, wildfire and earthquake picture for any point on Earth. Slower, and limited more tightly (see below). |
/api/scorecard | The track record: how many alerts, how many were withdrawn, and the evidence behind each rule. |
/api/anchors | The daily outside timestamps of the alert record, and proof files you can verify yourself. |
Filters for the alert endpoints
| Parameter | Meaning |
|---|---|
near=lat,lon | Only alerts within radius_km of this point. |
radius_km | Distance for near. Default 300. |
hazard | flood, wildfire, earthquake, severe_weather or debris_flow. |
status | open, claimed or resolved. Resolved includes alerts withdrawn as false. |
since | Only alerts recorded at or after this time, in Unix seconds. |
limit | Only the newest N alerts. |
The Atom feed accepts hazard, near, radius_km and limit (default 50, at most 200).
Reading an alert
alert_origintells you how it arose: an official warning from an authority, a satellite fire cluster, or a measurement of ours crossing a stated threshold. The track-record page lists the exact rules.- Official warnings carry the issuer's own severity and wording. Treat that as the authoritative part.
- An alert can be
resolvedbecause it was handled or because it was withdrawn as a false alarm. Checkresolutionbefore showing one as current. - A value of
"ai_predicted"inalert_originis a historical name kept so existing integrations keep working. These are measurement-based alerts, and the site now labels them Measured.
Limits
The weather data we depend on has a daily allowance, and our own alert scan needs most of it. So the API is limited to keep alerts flowing for everyone.
| Applies to | Limit per client (IP address) |
|---|---|
All /api/ requests | 240 per minute |
/api/predict/… and /api/nearby-help | 12 per minute and 100 per hour |
/api/chain (the whole record) | 10 per minute |
- 429 means you went over your own limit. Wait the number of seconds in the
Retry-Afterheader. - 503 from
/api/predict/locationmeans the shared allowance for new place lookups is used up for now. Places looked up recently are still answered, so try again afterRetry-After. - Place lookups are remembered for 5 minutes, and points within about a kilometre of each other share one answer.
- For a feed or a map, use
/api/alerts,.geojsonor.atomand poll no more than once a minute. Alerts change slowly.
Terms
- Free for non-commercial use, with no key. Please credit TerraAvert and link to terraavert.com. Each GeoJSON file and Atom feed already carries the credit line for you to keep.
- Commercial use is not offered yet. Part of our weather data comes from a free service that does not allow it. Please do not build TerraAvert into a paid product for now.
- Official warnings belong to their issuers: the U.S. National Weather Service, GDACS, the U.S. Geological Survey, NASA FIRMS, the Bahrain Meteorological Directorate and the Qatar Meteorology Department. Weather-derived values use Open-Meteo (CC BY 4.0). Keep the credit where you show them.
- Questions, feedback or commercial interest: write to [email protected].
- Not a substitute for official channels. An alert here can be late, wrong or missing. Do not rely on it alone where life or property is at stake, and follow local authorities.
- The API is provided as is, with no guarantee of availability. We will avoid breaking changes and will add new fields rather than rename existing ones, but this is version 1 and details may still be refined.