Name: Earthquake API - Real-time Global Seismic Data | QuotaLink
Brand: quotalink
SKU: api-quotalink-earthquake-api
Availability: InStock
Author: API Market

李乐

## Overview

Earthquake API delivers global seismic events from the USGS feed as clean, flat JSON. List recent quakes worldwide, find events near a coordinate within a radius you choose, or pull a single event by its USGS id.

Every event carries magnitude, depth, coordinates, a human-readable place name, a tsunami flag and a link to the USGS event page, so you can render a map pin or an alert without a second lookup.

## Features

- **Recent global activity**: the latest events worldwide, filterable by magnitude and time window.
- **Proximity search**: events within a radius of any latitude and longitude.
- **Single event lookup**: full detail for one USGS event id, including felt reports and alert level.
- **Magnitude filtering**: set a floor with `minmagnitude` to ignore the constant background of small tremors.
- **Time windows**: look back a chosen number of days rather than only at the newest events.
- **Tsunami and alert flags**: `tsunami` and PAGER `alert` come through on recent and lookup results.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Disaster monitoring dashboards**: track significant events as they are published.
- **Alerting and notifications**: notify users when a quake above a threshold occurs near a saved location.
- **Insurance and risk assessment**: pull historical activity around a property coordinate.
- **News and media**: auto-generate coverage from significant events with a source link.
- **Research and education**: seismic datasets for analysis and classroom use.
- **Travel and logistics safety**: check recent activity around a destination or route.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/earthquake-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### The event object

`/recent` and `/lookup` return the full object. `/nearby` returns a reduced form without `alert`, `tsunami`, `type` and `url`.

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | USGS event id, pass to `/lookup/{event_id}` |
| `magnitude` | number | Richter magnitude |
| `place` | string | Human-readable location, for example `31 km S of Nemuro, Japan` |
| `latitude` / `longitude` | number | Epicentre in decimal degrees |
| `depth_km` | number | Depth below surface in kilometres |
| `time` | integer | Event time as a Unix timestamp in **milliseconds** |
| `tsunami` | integer | `1` if a tsunami warning was associated, otherwise `0` |
| `alert` | string | USGS PAGER level (`green`, `yellow`, `orange`, `red`), often null |
| `type` | string | Event type, usually `earthquake` |
| `url` | string | USGS event page |
| `felt` | integer | Number of felt reports, lookup only, often null |

`time` is in milliseconds, so divide by 1000 before passing it to a seconds-based date constructor.

### Endpoints

#### GET /recent

Recent seismic events worldwide, newest first.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | No | Maximum events to return, default 10 |
| `minmagnitude` | query | number | No | Only return events at or above this magnitude |
| `days` | query | integer | No | Look back this many days, default 1 |

The magnitude floor parameter is `minmagnitude`. A plain `magnitude` value is ignored and you will get unfiltered results.

```bash
curl "https://prod.api.market/api/v1/quotalink/earthquake-api/recent?minmagnitude=5&days=7&limit=10" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 10,
  "earthquakes": [
    {
      "id": "us6000tnbv",
      "magnitude": 5.0,
      "place": "31 km S of Nemuro, Japan",
      "latitude": 43.045,
      "longitude": 145.6343,
      "depth_km": 96.855,
      "time": 1787651516700,
      "tsunami": 0,
      "alert": null,
      "type": "earthquake",
      "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000tnbv"
    }
  ]
}
```

`days` and `limit` interact: `limit` caps the result set, so a wide window with a small limit still returns only the newest events. To scan a full month, raise `limit` alongside `days`.

#### GET /nearby

Events near a coordinate.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `latitude` | query | number | Yes | Centre point latitude |
| `longitude` | query | number | Yes | Centre point longitude |
| `radius_km` | query | number | No | Search radius in kilometres |
| `limit` | query | integer | No | Maximum events to return, default 10 |
| `minmagnitude` | query | number | No | Only return events at or above this magnitude |

```bash
curl "https://prod.api.market/api/v1/quotalink/earthquake-api/nearby?latitude=35.68&longitude=139.65&radius_km=100&limit=5" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 1,
  "earthquakes": [
    {
      "id": "us6000tmta",
      "magnitude": 4.4,
      "place": "4 km N of Toride, Japan",
      "latitude": 35.9375,
      "longitude": 140.0688,
      "depth_km": 61,
      "time": 1787445144675
    }
  ]
}
```

Results here omit `alert`, `tsunami`, `type` and `url`. Call `/lookup/{event_id}` when you need them.

Omitting the coordinates returns `400` with `{"error":"latitude and longitude required","success":false}`.

#### GET /lookup/{event_id}

Full detail for a single event.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `event_id` | path | string | Yes | USGS event id from a recent or nearby result |

```bash
curl "https://prod.api.market/api/v1/quotalink/earthquake-api/lookup/us6000tnbv" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "earthquake": {
    "id": "us6000tnbv",
    "magnitude": 5.0,
    "place": "31 km S of Nemuro, Japan",
    "latitude": 43.045,
    "longitude": 145.6343,
    "depth_km": 96.855,
    "time": 1787651516700,
    "tsunami": 0,
    "alert": null,
    "felt": null,
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us6000tnbv"
  }
}
```

An unknown id returns `404` with `{"error":"Event not found: <id>","success":false}`.

#### GET /health

Service liveness. Takes no parameters and is useful for monitoring.

```json
{ "service": "earthquake-api", "status": "ok" }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | Required parameter or the `x-api-market-key` header is missing | Send `latitude` and `longitude` on `/nearby`, and check headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `404` | Event id not found | Use an id returned by `/recent` or `/nearby` |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `5xx` | USGS upstream error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **FREE**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **PRO**: 10,000 API units per month, soft limit, with overage billed per additional call.

Every endpoint costs one unit per request.

## Error Handling

Errors return JSON with an `error` field and `success: false`:

```json
{ "error": "latitude and longitude required", "success": false }
```

```json
{ "error": "Event not found: bogus-id", "success": false }
```

A query that matches nothing returns `200` with `count: 0` and an empty array, so check `count` before rendering. Seismic activity is bursty: a narrow window with a high `minmagnitude` legitimately returns zero events, which is not an error.

## Implementation Guide

### Example Code

```python
from datetime import datetime, timezone
import requests

BASE = "https://prod.api.market/api/v1/quotalink/earthquake-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}

def significant_near(lat, lon, radius_km=200, floor=4.0):
    r = requests.get(f"{BASE}/nearby", headers=HEADERS, timeout=20,
                     params={"latitude": lat, "longitude": lon,
                             "radius_km": radius_km, "minmagnitude": floor,
                             "limit": 20})
    r.raise_for_status()
    out = []
    for e in r.json()["earthquakes"]:
        when = datetime.fromtimestamp(e["time"] / 1000, tz=timezone.utc)
        out.append(f"M{e['magnitude']} {e['place']} at {when:%Y-%m-%d %H:%M} UTC")
    return out

for line in significant_near(35.68, 139.65):
    print(line)
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/earthquake-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function recentMajor({ floor = 5, days = 7, limit = 50 } = {}) {
  const url = `${BASE}/recent?minmagnitude=${floor}&days=${days}&limit=${limit}`;
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`Recent failed: ${res.status}`);
  const { count, earthquakes } = await res.json();
  if (!count) return [];
  return earthquakes.map((e) => ({
    id: e.id,
    magnitude: e.magnitude,
    place: e.place,
    when: new Date(e.time),
    tsunami: e.tsunami === 1,
    link: e.url,
  }));
}
```

### Performance Optimization

- Poll on a sensible interval. USGS publishes events within minutes, so once or twice a minute is plenty and anything faster only spends quota.
- Set a `minmagnitude` floor. Most of the global feed is tremors below magnitude 3 that no user cares about, and filtering server-side keeps responses small.
- Raise `limit` alongside `days` when scanning a wide window, rather than issuing many narrow queries.
- Cache by query. Past events do not change, so historical windows can be cached indefinitely and only the newest slice needs refreshing.
- Track the newest `time` you have seen and ignore anything older, instead of re-processing the whole response.

## FAQ

**Do I need an account with QuotaLink or USGS to use this API?**

No. Your API.market key is the only credential required.

**Why is my magnitude filter being ignored?**

The parameter is `minmagnitude`. A plain `magnitude` value is not recognised and the results come back unfiltered.

**What format is `time` in?**

A Unix timestamp in milliseconds. Divide by 1000 for libraries that expect seconds.

**Why does `/nearby` return fewer fields than `/recent`?**

It returns a reduced event object. Use `/lookup/{event_id}` for `alert`, `tsunami`, `type`, `felt` and the USGS link.

**Why did a 30 day window only return a few days of events?**

`limit` caps the response and defaults to 10. Raise it when widening `days`.

**What does `alert` mean?**

The USGS PAGER impact level: `green`, `yellow`, `orange` or `red`. It is null for most events, since only significant ones are assessed.

**Is zero results an error?**

No. It is a `200` with `count: 0`, which is a normal outcome for a narrow window or a high magnitude floor.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Access real-time earthquake data from USGS. Search by location, magnitude, time range. Free API with generous limits.