michiyomi API wiki

What is michiyomi?

michiyomi is an open API that uses vision-language models (VLMs) to turn public Mapillary street imagery into structured descriptions of physical street conditions. Query by latitude and longitude for sidewalks and estimated width, faded road markings, tactile paving, visual risk cues, and adjudicated changes at the same location over time—details that street geometry alone does not capture.

• Coverage: 588,220 processed scenes, concentrated in 13 of Tokyo’s 23 wards (release 2026-08-22-r1). Coverage is partial and uneven, including within covered wards.
• Japanese record content: Streetscape narratives and change evidence are currently returned in Japanese. Field names, metadata, and this reference are English-friendly.
• No authentication: No API key or registration is required.
• Read-only: There are no write endpoints.
• License: CC BY-SA 4.0; attribution is required.

Quickstart

The recommended sequence is: check coverage first, then retrieve content.

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"

Endpoints

Aliases: /v1/nearby → /v1/scenes/nearby; /v1/node/{id} → /v1/scenes/{id}. GET /v1 is the canonical live endpoint catalog.

Reading responses

All successful API responses use a common envelope. The excerpt below annotates key fields. The summary value remains Japanese because it is source record content, not interface text.

{
  "snapshot": "2026-08-22-r1",        ← release queried
  "request_id": "6aec71d3-…",         ← trace ID for this request
  "quality_policy": { "requested": "released", … },
  "license": { "id": "CC-BY-SA-4.0", "attribution": "…" },
  "results": [{
    "id": "964535250779795",
    "distance_m": 3,
    "capture_year": 2019,             ← the description reflects this year
    "position_source": "mapillary_computed",
    "generation": { "id": "gen1-codex", "status": "released" },
    "model": "gpt-5.6-sol",           ← generation provenance
    "summary": "施設: 一般道路 / 歩道: 左=あり… / 舗装: アスファルト…",
    "image_page": "https://www.mapillary.com/app/?pKey=964535250779795"
  }]
}

Inspect a live raw response. summary is display-oriented; use the scene detail’s structured analysis JSON for machine processing.

The scene detail’s three layers

GET /v1/scenes/{id}?include=metadata,machine,analysis keeps three fundamentally different layers separate.

When citing a value, identify its layer. See Design principle 3.1.

Dataset contents

• Scene definition: one representative image for each 20 m grid × 45° capture direction × year. The same location in a different year or direction is a different scene.
• 588,220 scenes were processed. Six anomalous capture-time records are quarantined from search and statistics, but remain directly retrievable by ID; therefore 588,214 are searchable.
• Coordinates: Mapillary’s SfM-corrected position is preferred (585,542 records); raw GPS is used when corrected coordinates are missing. position_source states which was selected.
• Machine layer: computed for every scene. Some fields remain absent when inputs are unavailable; /v1/meta is the canonical source for field coverage.
• Capture years: 2003–2026, with 99.95% captured in 2014 or later.
• Updates: immutable, versioned releases are published periodically. The response snapshot identifies the queried release.
• Geographic coverage: currently concentrated in 13 wards and uneven within them. A zero-result query is evidence of missing coverage, not evidence about the street itself.

Generations

Every verbalization carries a generation: the model family and output contract that produced it. A generation is a provenance label, not a quality ranking. Only generations that pass regression-comparison and calibration gates are released.

All 588,220 records are released. Six gen2 records are quarantined from search because of anomalous capture timestamps, leaving 510,538 searchable gen2 scenes.

The default API policy returns all released generations and collapses them to one result per location. Use generation=gen1-codex to select a generation explicitly. See GET /v1/generations for the live catalog.

Longitudinal changes

The changes dataset contains only findings that survived a falsification-oriented re-evaluation of images from the same location in different years: 2,522 records with status="supported".

• Each record includes both years, a Japanese category and narrative, adjudication status, and—on the detail endpoint—full evidence and verification metadata.
• Coordinates identify the center of a road group, not the exact position of the changed object.
• Adjudication is not independent third-party verification. Detection and review use context-separated sessions from the same model family, so shared systematic error may remain. The supported rate is a survival rate under attempted falsification, not an accuracy guarantee. See Design principle 3.4.

Important limitations

1. State the capture year. Every scene has capture_year. Never present a 2019 image description as a current observation.
2. Treat numeric values as estimates. Width and similar quantities are monocular-image estimates with confidence indicators, not survey measurements.
3. Zero does not mean absent in the real world. It means the dataset has no matching record. Call coverage first.
4. Do not fill in unknowns. The verbalization distinguishes absent, unknown, and outside the frame. Do not invent missing facts.
5. Expect Japanese narrative text. If you translate a record, retain the Japanese source text and record the translation method and date.

MCP for AI agents

The same data and honesty contract are available through a stateless Model Context Protocol Streamable HTTP server. For Claude Code:

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

The server’s discovery metadata includes the coverage-first workflow, license, Japanese-content notice, and rules against inventing facts absent from the data.

Rate limits, errors, and CORS

Rate limits

• Per IP: 300 REST requests per 60 seconds and 120 MCP requests per 60 seconds. Exceeding the limit returns 429 and a retry-after header.
• Use the API for nearby search rather than a full crawl. Use the published dataset for bulk analysis.

Error responses

4xx responses use a common JSON body. Parameter errors identify the relevant field.

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

Main codes: invalid_parameter (400), not_found (404), method_not_allowed (405), and rate_limited (429).

CORS and pagination

• CORS permits all origins (access-control-allow-origin: *), so browser clients may fetch the API directly.
• There is no pagination. Nearby search has a maximum limit of 50; vary the center or radius to cover a wider area.

License and attribution

The dataset is licensed under CC BY-SA 4.0. Show attribution whenever you use it, including in an AI-generated answer.

• A UI displaying source imagery must show a visible Mapillary logo and link to https://www.mapillary.com.
• Derived datasets inherit CC BY-SA 4.0’s share-alike requirement.
• Every API response includes an attribution string in its license field.

Interactive pages

For the reasoning behind the data design, read the design-principles white paper. For a dated build record, see development history.