book-map-japan

Overture Maps の Places データを出典とする、日本全国の書店マップ。

チェーン店をチェーン別のアイコンで表示し、広域ズームではチェーン店を優先して描画する。

アーキテクチャ

flowchart LR
    A["Overture Maps Places<br/>(S3 GeoParquet)"] -->|DuckDB CLI| B["pipeline<br/>fetch"]
    B --> C["out/book.geojson"]
    C -->|tippecanoe| D["out/book.pmtiles"]
    D -->|手動コピー| E["web/public/book.pmtiles"]
    E --> F["web<br/>Vite build"]
    F --> G["web/dist"]
    G -->|GitHub Actions| H["GitHub Pages"]

データ取得からタイル生成まで(pipeline)はローカルで手動実行し、生成した book.pmtiles をリポジトリへコミットする。CI は web のビルドと公開のみを行い、パイプラインは実行しない(DuckDB CLI・tippecanoe を CI へ持ち込まないため)。

ディレクトリ構成

パス	役割
pipeline/	Overture Places から書店 POI を取得し、GeoJSON を経て PMTiles を生成・検証する Node.js スクリプト群
pipeline/out/	パイプラインの生成物(book.geojson / book.pmtiles)。Git 管理外
web/	MapLibre GL JS + PMTiles のビューア。Vite でビルドする
web/index.html	Vite のエントリ
web/src/	main.js(地図本体)、chains.js(チェーン照合テーブル)
web/public/	Vite の public ディレクトリ。img/*.png(アイコン)と book.pmtiles が dist/ 直下へそのままコピーされる
web/dist/	ビルド生成物。Git 管理外
.github/workflows/	GitHub Pages へのデプロイワークフロー
openspec/	OpenSpec の仕様・変更提案

前提ツール

web のビルドだけであれば Node.js のみで足りる。pipeline の実行には npm で解決できない外部ツールが必要になる。

ツール	用途	備考
Node.js 20.19 以上(22 系は 22.12 以上)	pipeline / web の実行	web の vite@8 が要求する。pipeline だけなら 20 以上で足りる
DuckDB CLI	Overture Places(S3 上の GeoParquet)へのクエリ	spatial・httpfs 拡張を使用。初回実行時に自動で INSTALL される
tippecanoe	GeoJSON → PMTiles(MVT)変換
pmtiles CLI	生成した PMTiles の検証	verify:tiles で使用

セットアップと実行手順

1. データパイプライン(ローカル手動実行)

cd pipeline
npm install

# Overture のリリースバージョンは必須。未指定の場合は失敗する
OVERTURE_RELEASE=<release> npm run fetch   # → out/book.geojson
npm run build:tiles                        # → out/book.pmtiles (z10-14)
npm run verify:tiles                       # ズーム範囲とサンプル POI を検証

# 配信対象へ反映してコミットする
cp out/book.pmtiles ../web/public/book.pmtiles

対象は Overture Places の categories.primary = 'bookstore' かつ日本国内(bbox + addresses の国コード JP)、confidence >= 0.9 のレコード。

2. ビューア

cd web
npm install

npm run dev       # 開発サーバー(HMR)
npm run build     # → dist/
npm run preview   # dist/ を本番同等の構成で配信

book.pmtiles はブラウザが HTTP Range で部分取得する。配信元が Range に対応していることが動作の前提となるため、必要に応じて確認する。

curl -i -r 0-99 http://localhost:4173/book.pmtiles   # 206 Partial Content を期待

環境変数

変数	対象	既定値	説明
OVERTURE_RELEASE	pipeline	(なし・必須)	取得対象の Overture Maps リリースバージョン
BOOK_GEOJSON_PATH	pipeline	out/book.geojson	GeoJSON の入出力パス
BOOK_PMTILES_PATH	pipeline	out/book.pmtiles	PMTiles の入出力パス
BOOK_VERIFY_SAMPLE_SIZE	pipeline	5	検証時にサンプリングする POI 数

チェーン店アイコン

brand / operator / name を照合テーブルと部分一致で突き合わせ、以下のアイコンを割り当てる。いずれにも該当しない POI は book.png で表示する。

書店	アイコン
くまざわ書店	kumazawa.png
未来屋書店	miraiya.png
宮脇書店	miyawaki.png
紀伊國屋書店	kinokuniya.png
丸善	maruzen.png
ジュンク堂書店	junku.png
文教堂	bunkyo.png
三省堂書店	sansei.png
有隣堂	yurin.png
その他	book.png

チェーン店は z10 から、それ以外は z14 以上でのみ表示する。左上のプルダウンで特定チェーンだけに絞り込める。

テスト

cd pipeline && npm test   # node --test
cd web && npm test        # node --test

デプロイ

main への push、または GitHub Actions 上での手動実行(workflow_dispatch)で .github/workflows/deploy-pages.yml が起動し、web をビルドして web/dist/ を GitHub Pages へ公開する。

初回のみ、リポジトリの Settings > Pages > Source を GitHub Actions に設定する必要がある。

ワークフローはパイプラインを実行しないため、データを更新した場合は web/public/book.pmtiles を差し替えてコミットする。

OpenSpec 開発フロー

仕様と変更提案は OpenSpec で管理する。

コマンド	用途
/opsx:propose	変更を新規作成し、proposal / specs / design / tasks を生成する
/opsx:update	既存の変更の計画アーティファクトを改訂する
/opsx:apply	tasks.md に従って実装する
/opsx:archive	実装完了後に変更をアーカイブし、openspec/specs/ へ反映する

openspec list                              # 進行中の変更一覧
openspec status --change <name> --json     # アーティファクトの進捗
openspec validate <name> --strict          # 変更の検証

実装タスクは GitHub Issue としても登録されている(tasks.md の各見出し末尾が対応 Issue 番号)。

実装状況

現在 openspec/changes/book-map-japan の計画に沿って構築中で、pipeline/ と web/ のコードは未実装。進捗は Issues を参照。

出典

• POI データ: Overture Maps Foundation — ODbL
• 背景地図: OpenStreetMap contributors