gsimaps is the open source behind Japan's national web map

A national map service published as source, not as an app

The problem this project solves is a transparency one. GSI Maps is the web map that the Geospatial Information Authority of Japan operates at maps.gsi.go.jp, and it is the kind of service that people use daily without being able to read how it works. gsimaps publishes the source for it, and the README is explicit that what is provided here is the source of the Geospatial Information Authority of Japan operated map service. There is also a demo deployment built from this repository at gsi-cyberjapan.github.io/gsimaps, so you can see the code running before hosting it yourself. The intended user is a developer who wants to read, adapt or re-host Japan's official web map, and the stated hope at the end of the README is that people keep synchronising with the repository so that operations continue without incident.

It is a static site that wants a web server, not a file on disk

The usage instructions are short and carry an important caveat. The README says to download the whole set of files in the repository, place them on a web server, and open index.html. It then notes that opening index.html directly on the file system will work for many features, but that some features, such as the parts handling vector data, only work properly when hosted on a web server. That distinction decides how you set the project up. The repository is a collection of static assets rather than a build pipeline that outputs a bundle, so serving it is the deployment. The tree supports that reading, with css/, js/, js.lib/, features/, globe/, image/, infra/, layers_txt/ and a set of entry points including index.html, index_3d.html, index_m.html, index_pm.html, index_client.html, deprecated.html and link.html.

The dev server and the browser test harness

The package.json gives you a local server and an end to end test setup, and the two scripts are the only ones defined. The start script runs live-server bound to localhost on port 8080 with index.html as the entry file, and the test script runs two things at once, an http-server on port 4444 serving the current directory and cucumber-js with the success-first and kill-others options so the server is torn down when the run ends:

    "start": "live-server --host=localhost --port=8080 --entry-file=index.html",
    "test": "concurrently 'http-server . -p 4444 -s' cucumber-js --success first --kill-others"

The devDependencies explain the shape of that test setup, and they are worth reading as a statement of what the project considers a real check. cucumber-js at version 9 is the test framework, and puppeteer at version 24 is the browser driver, so the tests drive a real browser against a served copy of the site. There is also concurrently for running the two commands together, http-server and live-server for the two serving modes, and dotenv, which explains the .env file at the root of the repository.

Layer definitions live in files with their own separate specification

The map data is not baked into the code, and the README's See Also section points at two things that matter for anyone extending the map. The first is a layer definition file editing tool, provided from this repository, hosted at gsi-cyberjapan.github.io/gsimaps/config.html, and the page is a real file in the tree at the root as config.html. The second is the layer definition specification, provided from a separate repository, the layers-dot-txt-spec project, and the layers_txt/ directory in this repository holds the layer definition files themselves. The split is deliberate and it is the single most useful thing to understand about the layout. The map is a renderer plus a set of declarative layer descriptions, and the description format has its own versioned spec that can change without this repository changing.

The licence is three layers, and the middle one is not the code

The licensing is where this project needs the most care, and the README has a section of usage notes devoted to it. The repository's own licence is BSD-2-Clause, with the LICENSE file at the root and a separate LICENSE_LIBRARIES.md alongside it. Then there is the third party software: existing software such as Leaflet and jQuery is covered by its own licence. And then there is the content created by the Geospatial Information Authority, which the README says follows the public data usage terms based on the government open data strategy, version 1.0, and that a two-clause BSD licence is applied to it in the same way as for Leaflet. The README also states that if you send a pull request, the change becomes subject to that GSI credit and two-clause BSD licence at the moment it is merged. That is a broader grant than a typical contributor licence agreement, and it is the price of admission to the project.

A geocoding dependency and an unstable server side feature

Two operational caveats are stated in the same notes section, and both affect anyone planning to build on this. Part of the search function uses a service from the University of Tokyo CSIS, the simple geocoding service, and the README asks you to be aware of that dependency. Then there is a warning about the server side dynamic features the content calls, such as the place name search, which the README says are primarily assumed to be used from GSI Maps, that they are not necessarily always or long term available, and that the specification and usage of those features may change without notice. In other words, the map renders from static files you host, but some of the search behaviour is not yours to run. A fork that depends on that search path inherits a dependency you do not control.

A gh-pages branch, a 3D entry point and a service worker

A few structural details tell you how the project is deployed. The default branch is gh-pages, which is the branch GitHub Pages serves, so the live demo and the repository are the same thing rather than a build output. The tree includes index_3d.html along with index_3d_template.html, which is the 3D globe view, and a globe/ directory, and the README's tree listing also shows a manifest.json and a serviceworker.js, so the site is installable and cacheable as a progressive web app. The repository also has a .env file at the root, which is what the dotenv dependency is for, and a .editorconfig and .gitattributes, which is the level of hygiene you would expect from a project with this many contributors. The only tagged release information the repository carries is a single version field in package.json set to 1.0.0, and there are no GitHub releases, so the commit history on gh-pages is the version record.

Editorial conclusion

gsimaps suits a developer who wants to build on Japan's national basemap, who can host the whole tree themselves, and who is comfortable working in a repository whose default branch is gh-pages and whose companion layer definition spec lives in a separate project. It does not suit someone expecting a drop-in npm package, since the main entry point is an index.html served from a web server, and it does not suit a product that cannot accept the GSI content terms. Before adopting, read LICENSE and LICENSE_LIBRARIES.md alongside the README, check the layer definition file editing tool and the layers-dot-txt specification, and note that the last push to the repository was on 2026-10-08 with no GitHub releases published.

Frequently asked questions

Official sources

1. gsi-cyberjapan/gsimaps on GitHub
2. Issues
3. License: BSD-2-Clause
4. README