Volcash API

The world's first volcanic ash concentration API. Get real-time ash risk scores for any coordinate on Earth.

Free: 10,000 calls/monthREST + JSONPython & JS SDK

Quick Start

Get a volcanic ash risk score in 3 lines of code:

curl "https://api.volcash.io/v1/volcash?lat=31.58&lon=130.66&lang=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

Include your API key in the Authorization header:

Authorization: Bearer vc_free_xxxxxxxxxxxxxxxx

Free

10,000 calls/month

Prefix: vc_free_

Pay-as-you-go

$0.001/call

Prefix: vc_payg_

Enterprise

Unlimited + SLA

Prefix: vc_ent_

Endpoints

GET/v1/volcash

Get volcanic ash risk score for a coordinate.

Parameter	Type	Required	Description
lat	float	Yes	Latitude (-90 to 90)
lon	float	Yes	Longitude (-180 to 180)
lang	string	No	Language: en, ko, ja (default: en)

GET/v1/simple

Ultra-lightweight response (~30 bytes). Ideal for IoT devices.

87|caution|#FFFF00|true

GET/v1/activity

Activity-specific safety check (running, cycling, children, etc.).

Parameter	Type	Description
lat, lon	float	Coordinates
activity	string	general, running, cycling, hiking, children, elderly, delivery, construction, driving, tourism, farming, aviation

GET/v1/forecast

Hourly forecast (Free: 24h, Enterprise: 72h).

GET/v1/eruptions

List all currently active eruptions worldwide.

POST/v1/volcash/batch

Batch query up to 50 coordinates in one API call.

curl -X POST "https://api.volcash.io/v1/volcash/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations": [
    {"lat": 31.58, "lon": 130.66},
    {"lat": 37.75, "lon": 14.99}
  ]}'

Response Schema

{
  "status": "ok",
  "timestamp": "2026-04-04T12:00:00Z",
  "location": {
    "lat": 31.58,
    "lon": 130.66,
    "nearest_volcano": "Sakurajima",
    "distance_km": 8.2
  },
  "data": {
    "volcash_score": 142,        // 0-500 risk score
    "health_risk": "danger",     // safe|caution|danger|critical|emergency
    "go_outside": false,         // boolean safety indicator
    "summary": "High ash concentration...",
    "action_guide": "Stay indoors, wear KF94 mask...",
    "ash_concentration": 285.0,  // estimated µg/m³
    "confidence": 0.72,          // 0.0-1.0 data reliability
    "display": {
      "color": "#FF7E00",
      "level": "danger",
      "level_label": "Unhealthy",
      "badge_bg": "#FF7E00",
      "badge_fg": "#FFFFFF",
      "score_max": 500
    },
    "wind": {
      "speed_kmh": 25.0,
      "direction_deg": 225,
      "direction_label": "SW",
      "ash_heading": "NE"
    },
    "forecast": [
      { "hour": 1, "volcash_score": 150, "health_risk": "danger", "color": "#FF7E00" },
      { "hour": 2, "volcash_score": 135, "health_risk": "danger", "color": "#FF7E00" }
    ],
    "disclaimer": "This data is for informational use only..."
  },
  "meta": {
    "model_version": "v1.0",
    "data_age_minutes": 42,
    "data_source": "satellite+simulation"
  }
}

Risk Grade Scale

0 – 50Safe — No volcanic ash impact

51 – 100Caution — Sensitive groups take care

101 – 200Unhealthy — Avoid outdoor activity

201 – 350Dangerous — Stay indoors, seal windows

351 – 500Evacuate — Immediate danger to life

SDKs

Python

pip install volcash

JavaScript / TypeScript

npm install volcash

Rate Limits

Rate limit info is included in response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9842
X-RateLimit-Reset: 2026-05-01T00:00:00Z

Free tier: hard cap at 10,000 calls/month (HTTP 429 on exceed, no automatic billing). Pay-as-you-go: unlimited, $0.001/call after free quota.