# Volcanoes API
> The Smithsonian Global Volcanism Program (GVP) Holocene volcano list as an API — 1,215 volcanoes active within the last ~10,000 years. Look up any volcano by its GVP number (e.g. 211020 → Vesuvius) or name; search by name, country, type or region; or find every volcano within a radius of any coordinate (great-circle distance). Each record carries the volcano type, last-known eruption year, country/region, latitude/longitude, summit elevation, tectonic setting and a geological summary. Ideal for natural-hazard dashboards, travel/geography apps, education and earth-science tooling.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/volcanoes-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 45,000 calls/Mo, 8 req/s
- **Pro** ($17/Mo) — 220,000 calls/Mo, 20 req/s
- **Mega** ($43/Mo) — 1,100,000 calls/Mo, 50 req/s

## Endpoints

### Volcanoes

#### `GET /v1/nearby` — Volcanoes within a radius of a coordinate

**Parameters:**
- `lat` (query, optional, string) — Latitude (-90..90) Example: `35.68`
- `lon` (query, optional, string) — Longitude (-180..180) Example: `139.69`
- `radius_km` (query, optional, string) — Search radius in km (1-20000, default 500)
- `limit` (query, optional, string) — Max results (1-100, default 10)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/volcanoes-api/v1/nearby?lat=35.68&lon=139.69"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "total": 49,
        "center": {
            "lat": 35.68,
            "lon": 139.69
        },
        "results": [
            {
                "id": 283020,
                "name": "Hakoneyama",
                "type": "Complex",
                "region": "Northwestern Pacific Volcanic Regions",
                "country": "Japan",
                "landform": "Composite",
                "latitude": 35.233,
                "longitude": 139.021,
                "subregion": "Izu Volcanic Arc",
                "distance_km": 78.4,
                "elevation_m": 1438,
                "last_eruption": "2015",
                "geologic_epoch": "Holocene",
                "tectonic_setting": "Subduction zone / Continental crust (> 25 km)"
            },
            {
                "id": 283030,
                "name": "Fujisan",
                "type": "Stratovolcano",
                "region": "Northwestern Pacific Volcanic Regions",
                "country": "Japan",
                "landform": "Composite",
                "latitude": 35.361,
                "longitude": 138.728,
                "subregion": "Izu Volcanic Arc",
                "distance_km": 94,
                "elevation_m": 3776,
                "last_eruption": "1708",
                "geologic_epoch": "Holocene",
                "tectonic_setting": "Subduction zone / Continental crust (> 25 km)"
            },
            {
                "id": 283010,
     
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search by name with country / type / region filters

**Parameters:**
- `q` (query, optional, string) — Name search, e.g. fuji Example: `fuji`
- `country` (query, optional, string) — Country, e.g. Italy
- `type` (query, optional, string) — Volcano type, e.g. Stratovolcano, Caldera, Shield
- `region` (query, optional, string) — Volcanic region substring
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/volcanoes-api/v1/search?q=fuji&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "limit": 20,
        "query": "fuji",
        "total": 1,
        "offset": 0,
        "filters": {
            "type": null,
            "region": null,
            "country": null
        },
        "results": [
            {
                "id": 283030,
                "name": "Fujisan",
                "type": "Stratovolcano",
                "region": "Northwestern Pacific Volcanic Regions",
                "country": "Japan",
                "landform": "Composite",
                "latitude": 35.361,
                "longitude": 138.728,
                "subregion": "Izu Volcanic Arc",
                "elevation_m": 3776,
                "last_eruption": "1708",
                "geologic_epoch": "Holocene",
                "tectonic_setting": "Subduction zone / Continental crust (> 25 km)"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T03:47:07.707Z",
        "request_id": "a08cbf86-a673-465c-aa9f-3318f2d8c544"
    },
    "status": "ok",
    "message": "Volcanoes listed",
    "success": true
}
```

#### `GET /v1/volcano` — A single volcano by GVP number or name

**Parameters:**
- `id` (query, optional, string) — GVP volcano number, e.g. 211020 (Vesuvius) Example: `211020`
- `name` (query, optional, string) — Volcano name, e.g. Vesuvius

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/volcanoes-api/v1/volcano?id=211020"
```

**Response:**
```json
{
    "data": {
        "id": 211020,
        "name": "Vesuvius",
        "type": "Stratovolcano",
        "region": "European Volcanic Regions",
        "country": "Italy",
        "summary": "One of the world's most noted volcanoes, Vesuvius (Vesuvio) forms a dramatic backdrop to the Bay of Naples. The active cone was constructed within a large caldera of the older Monte Somma edifice, thought to have formed incrementally beginning about 17,000 years ago. The Monte Somma caldera wall has channeled lava flows and pyroclastic flows primarily to the south and west. Eight major explosive eruptions have taken place in the last 17,000 years, often accompanied by large pyroclastic flows and surges, such as during the 79 CE Pompeii eruption. Intermittent eruptions since 79 CE were followed by a period of frequent long-term explosive and effusive eruptions between 1631 and 1944. The large 1631 eruption produced pyroclastic flows that reached as far as the coast and caused great destruction. Many towns are located on the flanks, and several million people live within areas that could be affected by eruptions.",
        "landform": "Composite",
        "latitude": 40.821,
        "longitude": 14.426,
        "subregion": "Italian Peninsula Volcanic Provinces",
        "elevation_m": 1281,
        "last_eruption": "1944",
        "geologic_epoch": "Holocene",
        "tectonic_setting": "Subduction zone / Continental crust (> 25 km)"
    },
    "meta": {
        "timestamp": "2026-05-3
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & source

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/volcanoes-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Holocene volcanoes (active in the last ~10,000 years). id = GVP volcano number.",
        "total": 1215,
        "types": 27,
        "fields": [
            "id",
            "name",
            "type",
            "landform",
            "last_eruption",
            "country",
            "region",
            "subregion",
            "tectonic_setting",
            "geologic_epoch",
            "latitude",
            "longitude",
            "elevation_m",
            "summary"
        ],
        "source": "Smithsonian Global Volcanism Program (GVP) — Holocene Volcano List",
        "countries": 88
    },
    "meta": {
        "timestamp": "2026-05-31T03:47:07.823Z",
        "request_id": "892969e7-9d10-47c6-ae46-8b40eddb9a81"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/volcanoes-api
OpenAPI spec: https://www.oanor.com/api/volcanoes-api/openapi.json