Mini Tokyo 3D: A Real-Time 3D Map of Tokyo's Trains, Built on ODPT Data

What Mini Tokyo 3D renders, and who the build is aimed at

Mini Tokyo 3D is a 3D digital map of Tokyo's public transport system that updates in real time. Trains and aircraft move across the map, stations can be selected, and the camera can follow a single vehicle. The README describes it as "A real-time 3D digital map of Tokyo's public transport system" and points to a live demo at minitokyo3d.com.

The audience is narrower than the demo suggests. The repository ships a build pipeline, a VuePress documentation set in four languages, and a data directory of JSON files, which means the project expects someone who will run a build and host static files. The README's How to Build section is explicit that you need access tokens for both the transit data and the map tiles. There is no hosted embed, no iframe snippet and no npm-install-and-import path documented for third-party sites in the README. If you want a map on your own page, you are the operator.

Where the train positions come from: ODPT feeds and a prebuilt dataset

The data layer is the part that decides what this project can and cannot show. According to the README, the visualization is sourced from the Public Transportation Open Data Center, and that source "includes station information and train timetables as well as real-time data such as train location information and status information of multiple railway lines in the Greater Tokyo area." Two halves are therefore at work: a static dataset of stations, railways, operators, train types and points of interest, and a live feed of vehicle positions and line status.

The static half lives in the repository's data directory as JSON files. The README's translation section names them directly: airports.json, flight-statuses.json, operators.json, poi.json, rail-directions.json, railways.json, stations.json and train-types.json, alongside per-language dictionary files named dictionary-<ISO 639-1 code>.json. That layout tells you the map's vocabulary is curated by hand rather than inferred from the feed.

The rendering side is deck.gl layered over Mapbox. The package manifest lists @deck.gl/core, @deck.gl/geo-layers, @deck.gl/layers and @deck.gl/mapbox, plus several @turf packages for geometry work such as along, bearing, buffer and center-of-mass. Mapbox supplies the base map; deck.gl draws the moving vehicles and the transport geometry on top of it. That split is why two unrelated accounts are required before the map looks like anything.

Building Mini Tokyo 3D locally with npm run build-all

The README gives a three-step build. First install dependencies in the root directory:

npm install

The README states that the latest version of Node.js is required, so an older LTS release is not the documented target. Next, supply the access tokens as environment variables and run the full build. The README's example sets three variables inline:

MAPBOX_ACCESS_TOKEN=<Mapbox access token> \
MT3D_SECRET_ODPT=<access token for Public Transportation Open Data Center> \
MT3D_SECRET_CHALLENGE=<access token for Open Data Challenge for Public Transportation 2026> \
npm run build-all

The README says the script, dataset and static web page are generated in the build directory. The final step is deployment, not a running server: "place all the files in the build directory on your web server."

The repository's .env.example file describes a second route. It documents .env, .env.development and .env.production, with values in .env.<mode> taking precedence over .env and shell variables winning over both. For local work it recommends setting MT3D_DATA_URL to "data" to use locally generated data, which requires running npm run build-data first; leaving it empty uses the default remote data. The same file notes that the default Mapbox token is domain-restricted and will not work on localhost, so a local token is needed to display the base map. For development, npm run dev cleans the dev directory, regenerates the index, and runs a Rollup watcher alongside a serve process.

The token wall is the real adoption cost

The most likely reason a first attempt fails is not code. It is credentials. The README requires signing up at the Public Transportation Open Data Center and at Mapbox, and it adds a detail that is easy to miss: at the ODPT Center you need both tokens, one for ODPT Center and one for Challenge 2026. The build example names them MT3D_SECRET_ODPT and MT3D_SECRET_CHALLENGE, and .env.example labels both as deployment variables. A single token is not enough for the documented build.

The Mapbox side has its own trap. .env.example warns that the default token is domain-restricted and does not work on localhost. A developer who copies a token from an existing Mapbox project and sees a blank base map will spend time debugging the build when the problem is the token's domain list.

There is a second, quieter dependency: the data itself. The project does not ship its own real-time feed. If ODPT coverage for a given operator is missing or its status data is unavailable, Mini Tokyo 3D has nothing to animate for that line. The README does not document a fallback data source, and it does not describe what the interface shows when a feed is unreachable. Treat live coverage as an external condition you inherit, not something the project guarantees.

Plugins, and what the environment variables do not tell you

.env.example reserves five variables for plugins: MT3D_PLUGIN_PRECIPITATION, MT3D_PLUGIN_FIREWORKS, MT3D_PLUGIN_LIVECAM, MT3D_PLUGIN_PLATEAU and MT3D_PLUGIN_GTFS. Each is described as a path to a built plugin file, one per plugin, and unset plugins are simply omitted.

That is the whole contract in the repository's own documentation of the file. It tells you the extension points exist and that they are opt-in, but it does not tell you where the plugin source lives, how a plugin is authored, or what API a plugin receives. Anyone planning to extend Mini Tokyo 3D rather than deploy it as-is will need the developer guide, which the README links in English, Japanese, French and Simplified Chinese. The names themselves are informative: a GTFS plugin and a PLATEAU plugin suggest the project anticipates feeding it alternative transit datasets and Japanese 3D city models, but the environment file alone does not confirm what those plugins do.

How it compares with a plain 2D transit map

The obvious alternative for a Tokyo transit view is a conventional 2D vector map, of the kind a general-purpose mapping library renders from GTFS or a tile set. The difference is not cosmetic. A 2D map plots stops and lines; Mini Tokyo 3D animates individual vehicles along their routes, tilts and rotates the camera, offers an underground mode for the subway, and lets you track a single train or aircraft. That is a different data requirement: vehicle positions over time, not just network geometry.

It is also a different cost profile. A 2D map with static transit geometry can be built from open tiles and a stop list. Mini Tokyo 3D needs a live vehicle feed, a Mapbox account and a build step, and its geographic scope is fixed by the ODPT dataset to the Greater Tokyo area. If your question is "which line goes to this station," the 3D vehicle animation is machinery you do not need. If your question is "where is this train right now," the 2D map cannot answer it without the same live feed, at which point the 3D rendering is the part you are actually choosing.

Licence, maintenance and the cost of upgrading

Mini Tokyo 3D is released under the MIT license, and the package manifest declares "license": "MIT". MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. That covers the application code. It does not cover the data. The transit data comes from the Public Transportation Open Data Center and the map tiles come from Mapbox, and both are governed by their own terms, which the README does not restate. Anyone deploying this commercially should read those terms separately; the MIT grant on the code says nothing about your right to redistribute ODPT data or Mapbox tiles.

The repository is not archived, and the last push was on 2026-09-21. The most recent release is v4.0.0, published on 2026-08-14, preceded by two release candidates earlier that month. That cadence matters for upgrade planning: a major version number with a short RC cycle suggests the project does make breaking changes between majors, and the release notes are the place to check what moved. The README does not document a rollback procedure or a migration path between major versions, so pinning a working build and reading the release notes before moving is the practical approach. The repository also carries four separate developer guide files and four user guide files, which means documentation updates are part of the release work rather than an afterthought.

Editorial conclusion

Adopt Mini Tokyo 3D if you want a self-hosted, MIT-licensed 3D view of Greater Tokyo transport and you can obtain both an ODPT token pair and a Mapbox token, since the build fails to produce a usable map without them. Do not adopt it if you need a city outside the Greater Tokyo area, or if you want a drop-in widget with no build step and no external data accounts. Before committing, verify three things: that the ODPT Center and Challenge 2026 tokens you receive cover the railway lines you care about, that your Mapbox token is not domain-restricted in a way that breaks your deployment host, and that the plugin environment variables you intend to use point at built plugin files you actually have.

Frequently asked questions

Official sources

1. License: MIT
2. nagix/mini-tokyo-3d on GitHub
3. Project website
4. README
5. Releases