curl -H "X-API-Key: YOUR_KEY" https://jpseasons.dokos.dev/v1/sakura/forecast?city=tokyo

Endpoints

Sakura (Cherry Blossom)

# Current bloom status (which cities have bloomed)
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/sakura/status"

# Bloom forecast (historical average-based)
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/sakura/forecast?city=tokyo"

# Historical records (1953-present)
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/sakura/historical?city=tokyo"

# All 57 observation stations
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/sakura/locations"

# Travel recommendation
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/sakura/recommend?city=kyoto&dates=2026-03-25/2026-04-05"

Kouyou (Autumn Foliage)

Same pattern as sakura, under /v1/kouyou/:

status, forecast, historical?city=, locations, recommend?city=&dates=

Matsuri (Festivals)

# Search by region/month/category
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/matsuri/search?region=kansai&month=7"

# Upcoming festivals (next N days, default 30, max 90)
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/matsuri/upcoming?days=60"

# Festival detail (ID is kebab-case, e.g. gion-matsuri, aomori-nebuta)
curl -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/matsuri/gion-matsuri"

Error Handling

401 — Missing or invalid API key
404 — Unknown city ID or festival ID
429 — Rate limit exceeded (100/day free, 10K/day pro)
400 — Invalid parameters (bad date format, missing required param)

Common City IDs

tokyo, osaka, kyoto, yokohama, nagoya, sapporo, fukuoka, sendai, hiroshima, kobe, naha, kagoshima, nagano, kanazawa, matsuyama

Regions

hokkaido, tohoku, kanto, chubu, kansai, chugoku, shikoku, kyushu, okinawa

Usage Pattern

Use web_fetch or exec (curl) to call endpoints
Parse JSON response
Present data to user in natural language

Example — answering "When should I visit Kyoto for cherry blossoms?":

curl -s -H "X-API-Key: $KEY" "https://jpseasons.dokos.dev/v1/sakura/recommend?city=kyoto&dates=2026-03-25/2026-04-10"

Response includes likelihood, confidence, best_days, and alternatives.

japan-seasons

Japan Seasons API

Setup

Base URL

Authentication