みちよみ API wiki

みちよみとは

みちよみは、公開街路画像(Mapillary)を視覚言語モデル(VLM)で読み取り、道の物理的状態を構造化テキストにしたデータを配信するオープンAPIです。歩道の有無と幅、路面標示の摩耗、点字ブロック、リスクの手がかり、そして同一地点の経年変化——「地図の形」には載らない「道の見え方」を、緯度経度で検索できます。

• 収録範囲: 東京23区のうち13区・588,214シーン(2026-08-22時点)。8月末までに23区全域の処理を完了する予定です。
• 認証不要: APIキー・登録は不要です。
• read-only: 取得専用です。書き込み系エンドポイントは存在しません。
• ライセンス: CC BY-SA 4.0(出典表示が必要)。

クイックスタート

推奨の手順は「被覆を確かめてから、中身を引く」です。

curl "https://michiyomi.dev/v1/coverage?lat=35.6717&lon=139.7647"

curl "https://michiyomi.dev/v1/scenes/nearby?lat=35.6717&lon=139.7647&radius_m=150&limit=5"

curl "https://michiyomi.dev/v1/scenes/964535250779795?include=metadata,machine,analysis"

curl "https://michiyomi.dev/v1/changes/nearby?lat=35.6717&lon=139.7647&radius_m=500"

エンドポイント

別名: /v1/nearby → /v1/scenes/nearby、/v1/node/{id} → /v1/scenes/{id}。最新の仕様は常に GET /v1 の自己記述が正です。

レスポンスの読み方

全応答に共通のエンベロープが付きます。実際の応答(抜粋)で説明します。

{
  "snapshot": "2026-08-22-r1",        ← どの版のデータへの問い合わせか(release ID)
  "request_id": "6aec71d3-…",         ← 問い合わせの追跡ID
  "quality_policy": { "requested": "released", … },
  "license": { "id": "CC-BY-SA-4.0", "attribution": "…" },
  "results": [{
    "id": "964535250779795",
    "distance_m": 3,
    "capture_year": 2019,             ← 撮影年。記述はこの年の状態
    "position_source": "mapillary_computed",  ← SfM補正座標か生GPSか
    "generation": { "id": "gen1-codex", "status": "released" },
    "model": "gpt-5.6-sol",           ← どのモデルが言語化したか(来歴)
    "summary": "施設: 一般道路 / 歩道: 左=あり(分離歩道,5m), 右=あり(分離歩道,4m),
                有効幅約4m, 点字ブロックあり … / 舗装: アスファルト・補修跡あり(旧)・
                標示摩耗進行方向矢印20% / リスク: 街路樹による交差点方向の死角; …",
    "image_page": "https://www.mapillary.com/app/?pKey=964535250779795"
  }]
}

上記は注釈を書き込んだ抜粋です。生の応答はこの実URLで確認できます。summaryは表示用の要約であり、機械処理にはシーン詳細のanalysis(構造化JSON)を使ってください。

シーン詳細の三層構造

GET /v1/scenes/{id}?include=metadata,machine,analysis は性質の違う3層を分離したまま返します。

analysis層は推定を含みます。引用時はどの層の値かを明示してください(この分離の設計意図は設計思想 原則3.1)。

データセットの中身

• シーンの定義: 20mグリッド×撮影方位45°×年で集約した代表画像1枚。同じ場所でも年・向きが違えば別シーンです(これが経年比較の素材になります)。
• 処理総数は588,220。撮影時刻異常の6件を検索・統計の対象から除外しており(IDの直接参照では取得可能)、検索対象は588,214です。
• 座標はSfM補正座標(computed)を原則採用し(585,542件)、欠損時のみ生GPS。どちらを使ったかはposition_sourceに明示。
• 機械層は全シーンに対して計算を実行済み。入力の欠損により項目ごとに未充足があり(travel_bearing 99.6%・abs_objects 88.5%など)、充足率は/v1/metaが正本です。
• 撮影年の範囲は2003〜2026年ですが、99.95%は2014年以降です(2013年以前は286シーン)。
• 更新はversionedなreleaseとして不定期に行われます。全応答のsnapshotフィールドでどの版への問い合わせだったかを特定できます。
• 収録範囲は現在13区。区単位で処理を進めており、8月末までに23区全域の処理を完了する予定です。

世代(generation)

各言語化には「どのモデル系列が生成したか」を表す世代が付きます。世代は品質の優劣ではなく来歴のラベルで、採用ゲート(回帰比較・較正検証)に合格した世代だけが配信されています。

件数は検索対象ベース。処理ベースではgen2は510,544件で、うち撮影時刻異常の6件を検索対象から除外しています(データセットの中身参照)。

既定APIは全世代を配信し、1地点1件に折りたたんで返します。特定世代だけを見たい場合はgeneration=gen1-codexのように指定してください。世代カタログはGET /v1/generationsにあります。

経年変化データ

同一地点・別年の画像比較から得た「変わった」という所見のうち、反証を試みる再検証(裁定)を通過したもののみを収録しています(supported 2,522件)。裁定を通らなかった所見は入っていません。

• 各変化には二時点の年・カテゴリ・所見の記述・裁定結果が付きます。詳細(/v1/changes/{id})では根拠(evidence)全文と検証メタを確認できます。
• 座標は道路グループの中心であり、変化した対象物の位置そのものではありません。
• 裁定は反証を試みる再検証であり、独立した第三者検証ではありません。supported率は「正解率」ではなく「反証に耐えた割合」です(裁定方法の詳細は設計思想 原則3.4)。

データを読むときの注意

1. 撮影年を明示する — 全結果にcapture_yearが付きます。2019年の画像の記述を現在の状態として語らないでください。
2. 数値は推定値として扱う — 幅員などは単眼画像からの推定で確信度つき。測量値ではありません。断定を避けてください。
3. 0件は「何もない」ではない — 収録がないだけです。まずcoverageで被覆を確認してから答えてください。
4. 「不明」を埋めない — 言語化は「なし」「不明」「画角外不明」を区別して申告します。データに無いことを推測で補完しないでください。

MCPで使う(AIエージェント)

同じデータ・同じ品質契約の上に、Model Context Protocol(Streamable HTTP・stateless)のサーバーがあります。Claude Codeなら1行で接続できます。

claude mcp add --transport http michiyomi https://michiyomi.dev/mcp

ツール定義には利用手順(coverageで被覆を確認してから中身を引く)と正直性の規約が含まれています。

レート制限・エラー・CORS

レート制限

• IP単位で REST 300リクエスト/60秒、MCP 120リクエスト/60秒。超過時は429とretry-after: 60ヘッダが返ります。
• 全件クロールではなく、近傍検索として使ってください。データセット全体の一括公開は別途準備中です。

エラー応答

4xx系は共通形式のJSONボディを返します。パラメータ起因のエラーはfieldで対象を特定できます。

{"error": {"code": "invalid_parameter",
           "message": "lat must be between -90 and 90",
           "request_id": "bc61f874-…", "field": "lat"}}

主なコード: invalid_parameter(400) / not_found(404) / method_not_allowed(405。書き込み系メソッドは/mcpを除きすべて405) / rate_limited(429)。

CORS・ページネーション

• CORSは全オリジン許可(access-control-allow-origin: *)。ブラウザから直接fetchできます。
• ページネーションはありません。近傍検索はlimit上限50で、それより広く取りたい場合は半径・中心を変えて問い合わせてください。

ライセンス・出典表示

本データはCC BY-SA 4.0です。利用時(AIの回答に使う場合を含む)は出典を表示してください。

• 画像そのものを表示するUIには、Mapillaryロゴの視認可能な表示と https://www.mapillary.com へのリンクが必要です。
• 派生データはCC BY-SA 4.0を継承します(share-alike)。
• 全応答のlicenseフィールドに帰属文字列が同梱されています。

体験ページ

このデータがどういう思想で作られているか、今後どこへ向かうかは 設計思想(ホワイトペーパー) へ。いつ・何から作られたかは 開発の記録 へ。