TELURICOTELURICO FOR DEVELOPERS
Build with earthquake context.
Bring source-attributed earthquake reports into your dashboards, maps and research. A public, read-only API with explicit freshness and predictable contracts.
curl --fail-with-body 'https://www.telurico.app/api/v1/events?area=WORLD&hours=24'01 / Endpoints
Endpoints
All documented endpoints accept GET and OPTIONS. Public browser access uses CORS without credentials. Private account and operator APIs require their own authorization and are excluded from this public contract.
| Method / path | What it returns |
|---|---|
GET /events | Filtered catalog, 25 events per page |
GET /events/{source}/{id} | One retained event with source identity |
GET /sources | Freshness, attribution and dataset licenses |
GET /regions | Supported areas and approximate extents |
GET /status | Service capabilities and limitations |
GET /community?country=NI | Thresholded participation for one country |
GET /resources?country=BB&locale=en | Official and humanitarian directory links |
https://www.telurico.app/api/v1
02 / API explorer
API explorer
/api/v1/events?area=WORLD&hours=24Response
Waiting for a request{}03 / Data contract
Data contract
UTC timestamps use Unix milliseconds. Magnitudes and depths can be null; never coerce unknown values to zero. Preserve magnitude_type, review_status and negative source depths. Distance is from your chosen center, not a shaking-intensity estimate.
Use WORLD, LATAM, CARIBBEAN or a supported ISO-2 code. Areas are approximate browsing rectangles, including some neighboring or offshore events. For nearby reports, pass latitude and longitude together; radius is 10–2,000 km. This center is your query choice, not a device measurement.
No contacts, chat, check-ins, exact participating-device locations or raw motion traces are public. Community counts are privacy-thresholded, self-reported participation; they do not establish detection quality.
| Field | Meaning |
|---|---|
source + id | USGS / EMSC + provider ID |
time / updated | UTC · Unix ms |
magnitude / depth_km | number | null |
review_status | reviewed | automatic | unknown |
state | current | stale | unavailable |
early_warning | false |
04 / Integration guide
Integration guide
Inspect state, generated_at and fetched_at. Stale snapshots are retained through source outages. An unavailable or empty feed is not an all-clear. EMSC freshness uses collection time because its response has no generated timestamp.
Upsert on (source, id) and retain updated. Events can be revised or withdrawn. Compare a complete fresh window before removing an event. Pagination is live, so deduplicate across pages; snapshot_at is informational and does not freeze a result set.
Poll at most once per minute, cache results, and use exponential backoff with jitter after network errors or HTTP 503. Provider catalogs update at different intervals; polling faster cannot make source reports arrive sooner.
Compatible fields may be added in v1. Ignore unknown fields. Breaking contract changes require a new API version. No delivery SLA or warning performance is claimed.
05 / Errors & limits
Errors & limits
60 requests per minute per client address. Check RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). On HTTP 429, wait for Retry-After. Shared corporate networks share this limit. Contact us before higher-volume use.
400 | Invalid, unknown or repeated query parameter |
|---|---|
404 | Unknown route or event outside the retained catalog |
405 | Unsupported HTTP method |
429 | Rate limit; honor Retry-After |
503 | Temporary data-store failure; retry with backoff |
{"error":"invalid_filter","request_id":"…"}
X-Request-ID · X-API-Version · RateLimit-Remaining · Retry-After
06 / Sources & licensing
Sources & licensing
Keep the original source link, attribution, license link and the fact that TELURICO normalized fields. USGS and EMSC can describe the same earthquake; two records do not imply independent corroboration. Neither provider endorses TELURICO.
Plan an integration with us ↗