Japan Seasons API

Query Japanese seasonal data — cherry blossom forecasts, autumn foliage tracking, and festival search. Use when a user asks about sakura bloom dates, best ti...

Security Scan

The skill appears to do what it says (query a third‑party Japan seasons API) and asks for a standard API key, but the registry metadata fails to declare that key—verify the key handling before use.

Purpose & Capability

The SKILL.md documents endpoints for sakura, kouyou, and matsuri on https://jpseasons.dokos.dev which matches the skill's name and description. However, the registry metadata lists no required env vars or primary credential while the runtime instructions explicitly require an X-API-Key; this metadata omission is inconsistent.

Instruction Scope

Instructions are narrow and consistent: call the documented API endpoints (via web_fetch or curl), parse JSON, and present results to the user. The instructions do reference an environment variable ($KEY) or passing the key in headers, which is expected for this API.

Install Mechanism

No install spec and no code files — instruction-only skills have minimal disk footprint and nothing is downloaded or executed by default beyond normal network calls.

Credentials

The SKILL.md requires a per-user API key (X-API-Key) from jpseasons.dokos.dev, which is appropriate for this purpose. The registry metadata, however, does not declare any required env vars or primary credential; this mismatch should be resolved so users know what secrets to supply.

Persistence & Privilege

The skill does not request persistent presence (always is false), does not modify other skills or system config, and does not declare writing to disk. Autonomous invocation is allowed (platform default) but is not combined with other concerning privileges.

Assessment

This skill is coherent: it calls a third‑party API that requires an X-API-Key. Before installing, confirm the registry metadata is updated to declare the API key requirement (so the platform can surface the secret prompt), and only provide a key you trust to the jpseasons.dokos.dev service. Be aware the agent will make outbound HTTP requests (curl or web_fetch) to that domain and is subject to the service's rate limits (free tier 100/day). If you need stronger privacy, consider using a dedicated key with limited scope or rate limits, and verify the jpseasons.dokos.dev domain and dashboard are legitimate.

Query cherry blossom, autumn foliage, and festival data for Japan.

Setup

Get a free API key at https://jpseasons.dokos.dev/dashboard (100 req/day).

Store the key as an environment variable or pass directly in headers.

Base URL

https://jpseasons.dokos.dev

Authentication

All requests need X-API-Key header:

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

1. Use web_fetch or exec (curl) to call endpoints
2. Parse JSON response
3. 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.