# Japan Seasons API

> REST API for Japanese seasonal data. Cherry blossoms, autumn foliage, and festivals.

## Base URL
https://jpseasons.dokos.dev

## Authentication
All /v1/* endpoints require an API key via `X-API-Key` header or `api_key` query parameter.
Get a free key at https://jpseasons.dokos.dev/dashboard

## Endpoints

### Sakura (Cherry Blossom)
- GET /v1/sakura/status — Current bloom status across 57 JMA observation stations
- GET /v1/sakura/forecast — Bloom date forecast based on 30-year historical averages
- GET /v1/sakura/historical?city={id} — Historical bloom records (1953-present)
- GET /v1/sakura/locations — List all 57 observation stations with coordinates
- GET /v1/sakura/recommend?city={id}&dates=YYYY-MM-DD/YYYY-MM-DD — Best time to visit recommendation

### Kouyou (Autumn Foliage)
- GET /v1/kouyou/status — Current leaf color status across 53 stations
- GET /v1/kouyou/forecast — Color change forecast
- GET /v1/kouyou/historical?city={id} — Historical records
- GET /v1/kouyou/locations — List all observation stations
- GET /v1/kouyou/recommend?city={id}&dates=YYYY-MM-DD/YYYY-MM-DD — Best time to visit

### Matsuri (Festivals)
- GET /v1/matsuri/search?region={region}&month={1-12}&category={cat} — Search 50+ festivals
- GET /v1/matsuri/upcoming?days={30} — Upcoming festivals
- GET /v1/matsuri/{id} — Festival details

## MCP (Model Context Protocol)
Endpoint: https://jpseasons.dokos.dev/mcp
Transport: Streamable HTTP
10 tools available for AI agent integration.

## Pricing
- Free: 100 requests/day, current year data
- Pro ($29/mo): 10K requests/day, historical data, webhooks
- Enterprise: Custom pricing, SLA

## Data Sources
- Japan Meteorological Agency (気象庁) — sakura & kouyou observations since 1953
- Curated festival database — 50+ major Japanese festivals

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

## Links
- Dashboard: https://jpseasons.dokos.dev/dashboard
- GitHub: https://github.com/ko-syun/japan-seasons-api
- MCP: https://jpseasons.dokos.dev/mcp