# Japan Seasons API — Full Specification

# 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


## Detailed Response Formats

### Sakura Status Response
```json
{
  "data": {
    "season": 2026,
    "summary": {
      "total_stations": 57,
      "bloomed": 30,
      "full_bloom": 15,
      "not_yet": 20,
      "ended": 7
    },
    "stations": [{
      "location": { "id": "tokyo", "name": "Tokyo", "prefecture": "Tokyo", "region": "kanto", "coordinates": { "lat": 35.6894, "lon": 139.6917 } },
      "status": "full_bloom",
      "bloom_date": "2026-03-20",
      "full_bloom_date": "2026-03-27",
      "tree_species": "somei_yoshino"
    }]
  }
}
```

### Forecast Response
```json
{
  "data": {
    "season": 2026,
    "locations": [{
      "location": { "id": "tokyo", "name": "Tokyo" },
      "estimated_bloom_window": { "earliest": "2026-03-14", "typical": "2026-03-22", "latest": "2026-03-31" },
      "estimated_full_bloom_window": { "earliest": "2026-03-21", "typical": "2026-03-30", "latest": "2026-04-07" },
      "based_on_years": 30
    }]
  }
}
```

### Historical Response
```json
{
  "data": {
    "location": { "id": "tokyo", "name": "Tokyo" },
    "records": [{ "year": 2025, "bloom_date": "2025-03-20", "full_bloom_date": "2025-03-28" }],
    "statistics": {
      "years_observed": 73,
      "earliest_bloom": { "date": "03-14", "year": 2023 },
      "latest_bloom": { "date": "04-11", "year": 1984 },
      "average_bloom": "03-26",
      "trend": "Earlier by ~2 days per decade since 1990"
    }
  }
}
```

### Recommend Response
```json
{
  "data": {
    "query": { "city": "kyoto", "dates": "2026-03-28/2026-04-05" },
    "recommendation": {
      "likelihood": "high",
      "confidence": 0.95,
      "summary": "Kyoto typically reaches full bloom in April.",
      "best_days": { "estimated_full_bloom_period": "2026-03-24/2026-04-10" },
      "alternatives": [{ "city": "tokyo", "name": "Tokyo" }]
    }
  }
}
```

### Matsuri Search Response
```json
{
  "data": [{
    "id": "gion-matsuri",
    "name_en": "Gion Matsuri",
    "name_ja": "祇園祭",
    "city": "Kyoto",
    "region": "kansai",
    "month": 7,
    "category": ["float", "traditional"],
    "estimated_visitors": 800000
  }],
  "meta": { "total": 50, "limit": 20, "offset": 0 }
}
```

## City IDs (Sakura)
tokyo, osaka, kyoto, yokohama, nagoya, sapporo, fukuoka, sendai, hiroshima, kobe, naha, kagoshima, nagano, kanazawa, matsuyama, etc.

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

## Error Codes
- 401: MISSING_API_KEY — No API key provided
- 403: INVALID_API_KEY — Key invalid or deactivated
- 429: RATE_LIMIT_EXCEEDED — Daily limit reached
- 400: MISSING_PARAMETER / INVALID_DATE_FORMAT
- 404: INVALID_CITY / NOT_FOUND