# Japan Trip Tools — open data

This directory publishes the machine-readable data behind the [Bloom Planner](https://triptoolsjapan.com/bloom/), a "will I catch the cherry blossoms / autumn leaves on my dates?" tool.

## Files

### bloom.json
30-year climatological normals (first-bloom / full-bloom / peak-color / end dates, and year-to-year standard deviation in days) for each of 19 Japanese cities, for both events (`sakura`, `koyo`). Derived from Japan Meteorological Agency (JMA) observation records — see https://www.data.jma.go.jp/sakura/data/. `normal_end` (viewing-window close) is a documented modeling assumption, not a JMA-observed value.

### offsets.json
Our hand-maintained, **append-only** archive:
- `entries[]` — a dated snapshot of our editorial "peak is running ±N days vs normal" call for a Japan region, informed by (but never reproducing) public commercial forecasts. New rows are appended in-season; old rows are never edited or deleted.
- `actuals[]` — filled in after a season ends, from JMA's own published observation for that year. This turns the entries above into a graded predicted-vs-actual track record over time — a record that cannot be produced retroactively; it only exists because we started keeping it.

## License & attribution
CC-BY-4.0 (https://creativecommons.org/licenses/by/4.0/). Attribution: "Japan Trip Tools (triptoolsjapan.com)". JMA's own observation values are factual public data; only our combination/derivation and the `offset_days` editorial judgments are original work under this license. No commercial forecast table, map, or date list is ever reproduced.

## Update cadence
`bloom.json` is regenerated from JMA's published normals roughly once a season. `offsets.json` `entries[]` is updated in-season on a roughly weekly cadence; `actuals[]` is appended once per city per season, after JMA publishes that year's observation.

## Contact
Corrections or questions: hello@triptoolsjapan.com