japanese-addresses: open address data down to the town block level
全国の町丁目レベル（277,191件）の住所データのオープンデータ
At a glance
- What is it?
- Geolonia's japanese-addresses repository publishes Japanese address data as open data, with a CSV, a SQLite database and a JSON API that goes down to town and sub-town level, each record carrying a representative point. The README states the data itself is no longer being updated and points to a successor project.
- Who is it for?
- japanese-addresses is still usable as a fixed snapshot of Japanese addresses, and the town level JSON API is a quick way to get a searchable list of municipalities and their districts. It is not a good basis for anything that needs current data, because the README states the data in this repository is no longer being updated and points to japanese-addresses-v2 instead.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 80 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 23, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What the repository publishes and what it no longer maintains
The first thing the README tells you is that the data in this repository is not currently updated, and that the project still being maintained is japanese-addresses-v2, built on the address base registry. That warning sits at the very top of the file, above everything else, and it changes how the rest of the repository should be read.
What remains here is still substantial. The project publishes address data for the whole country down to town, district and sub-district level, and the README states the figure as 277,543 records. The repository description quotes a slightly different count of 277,191, so the two numbers in the project itself do not agree exactly, which is a reminder that the count is tied to a particular build.
The data is derived from the Ministry of Land, Infrastructure, Transport and Tourism's large district level position reference information, distributed through its position reference download service. The README explains the reason for the project's existence in one line: the source data is updated only once a year, whereas the data distributed here is updated monthly. The monthly update was the value proposition, and that is precisely the part that has moved to the successor project.
For a reader, the practical conclusion is that this repository is a historical snapshot with a complete build pipeline, not a live feed.
File formats, columns and the sort order
Two distributions are offered. latest.csv is a CSV file, and latest.db is a binary format that SQLite 3 can read. Both are linked directly from the README, along with a link to the release notes on the releases page.
The CSV carries fourteen columns, and the list is worth reading because it shows how much localisation the project does. Each address has a prefecture code, and the prefecture name in kanji, in kana and in romaji. The same three-way treatment applies to the city, ward, town and district name, with the town level name given as 大字町丁目名 and the smaller sub-district as 小字・通称名. The final two columns are the latitude and longitude of a representative point, marked as such.
The sort order is specified precisely, and it is a hierarchy of five keys: prefecture code ascending, then city code ascending, then the kana form of the town name ascending, then the town name in character code order, then the sub-district name in character code order. The README spells out the same idea in prose, that records with the same prefecture code are ordered by city code, and so on down the chain. A consumer that merges this file with another address dataset can rely on the order rather than re-sorting it.
The romaji and kana columns are generated rather than transcribed, which is where the supporting dependencies come in. The package.json lists @geolonia/normalize-japanese-addresses, @geolonia/japanese-numeral, encoding-japanese, iconv-lite and js-hira-kata-romanize, so normalisation, numeral handling and transliteration are handled by separate packages rather than by ad hoc code.
The JSON API and the two endpoint shapes
An API is served on top of the CSV, with two endpoint shapes. The first lists prefecture names as keys and city names as array values, and the README shows the shape with Hokkaido, Aomori and Iwate entries opening the object.
The second endpoint drills into a prefecture and a city, with the path built from the prefecture name and the city name, and the README notes that both must be URL encoded. Each element of the returned array carries a town name, a sub-district name, a latitude and a longitude.
The sample response in the README shows four records for the same town, each with a different sub-district name, so the data reaches the level of a named neighbourhood within a town. The town level endpoint does not cover every place name, and the README flags that in its notes section, which is worth knowing before you build an address picker on top of it and assume completeness.
The API directory structure is laid out in the README as a tree, running from api down through ja, the prefecture, the city, the town, and then to two leaf files. One leaf is the block level list keyed by gaiku, the block symbol, and the other is the residential display list keyed by gaiku and jyukyo, the dwelling number. The block level and residential display endpoints are optional extras that have to be built explicitly, they are not part of the default output.
How a representative point is chosen for a small district
The interesting engineering is in the coordinates. For an address that includes a sub-district, the block level position reference information offers several points belonging to the same block, and the project has to collapse them into one point to return in the API.
The method, as the README describes it, takes three steps. Assume points A, B and C belong to the block for an address such as 長野県長野市篠ノ井塩崎長谷. Build the smallest rectangle that encloses A, B and C, a bounding box, and take its centre. Then pick the point among A, B and C that is closest to that centre, and return that point's coordinates as the representative point for the address.
The reason for this approach is that a plain centroid of the points would fall in the wrong place for certain shapes. The README shows two illustrations for the failure cases, a crescent problem and an enclave problem, where the territory of a block curves or jumps, and a naive average lands outside the block. Choosing the nearest actual point to the bounding box centre keeps the coordinate inside the address it belongs to.
The tooling matches the algorithm. The dependencies include @turf/center for the bounding box centre and @turf/nearest-point for the closest-point selection, so the two steps of the calculation are done by turf rather than by handwritten trigonometry.
Building the data and the API from the source
The build is driven by npm scripts, and the README gives the full sequence. Cloning, installing and running the two main builds covers the standard case.
$ git clone [email protected]:geolonia/japanese-addresses.git
$ cd japanese-addresses
$ npm install
$ npm run build # 元データのダウンロードと latest.csv 及び latest_gaiku.csv の作成を行います
$ npm run build:api # latest.csv から API を作成しますThe build script downloads the source data and produces latest.csv and latest_gaiku.csv, and the api script turns latest.csv into the JSON tree.
Three optional commands extend the output. The gaiku builder adds the block level API, the residential download script pulls the address base registry data, and the jyukyo builder adds the dwelling symbol level API.
$ node bin/build-gaiku-api.mjs # 街区レベルの API を追加で作成します
$ sh bin/download-residential.sh # ベースレジストリのデータのダウンロードを行います
$ node bin/build-jyukyo-api.mjs # 住居符号レベルの API を追加で作成しますThe README names the three optional scripts, while package.json is where build maps to node bin/build.js and build:api to node bin/build-api.js. The test script is worth noting, because it passes fixed arguments to node bin/build.js 20,1,29,19,13 and then npx mocha, which is a way of building a known slice of the source for a deterministic test. The test suite uses mocha with chai, and the mocha spec pattern points at the test/ directory.
Where the dataset is the wrong tool, and the licence split
The first limitation is freshness, and the README is unambiguous that the data in this repository is not updated. Any product that needs new municipalities, renamed districts or the latest block boundaries should go to the successor project rather than rebuilding this one.
The second is coverage. The town level endpoint does not list every place name, and the fourteen-column CSV has a fixed granularity that stops at a representative point per address rather than a polygon. If your requirement is a boundary, this is the wrong dataset.
The third is the build dependency. Rebuilding requires downloading the source position reference data and the residential registry, which means network access to the ministry's service and to the Digital Agency dataset, and a fair amount of processing for a full country. The build also depends on Node tooling, with sqlite3 and unzipper in the dependency list for producing the database and reading the source archives.
The licence deserves careful reading, because it is split in two. The data itself is published under CC BY 4.0, which requires attribution, while the data generation scripts bundled in the repository are MIT licensed, as stated in the note under the licence section. So a product that embeds the address data has a Creative Commons attribution obligation, while a fork of the build scripts does not. The repository also names a sponsor, the Real Estate Tech Association, and a Ruby gem, JapaneseAddressParser, as a project built on the data.
Editorial conclusion
japanese-addresses is still usable as a fixed snapshot of Japanese addresses, and the town level JSON API is a quick way to get a searchable list of municipalities and their districts. It is not a good basis for anything that needs current data, because the README states the data in this repository is no longer being updated and points to japanese-addresses-v2 instead. Verify which project you need first, and check the record count against the source before you trust it for a coverage requirement.
Frequently asked questions
Is the data in Geolonia japanese-addresses still updated?
No. The README opens by stating that the data in this repository is not currently updated, and points to the japanese-addresses-v2 repository, which is built on the address base registry and is the project still being maintained.
What granularity of Japanese address does the japanese-addresses dataset cover?
It covers the whole country down to town, district and sub-district level, which the README puts at 277,543 records. Each record carries kanji, kana and romaji names for the prefecture, city and town, the sub-district name, and a representative latitude and longitude.
How is the representative point for a small address chosen?
The project takes the multiple block level points for an address, builds the smallest bounding rectangle around them, takes the rectangle's centre, and returns the point among the originals closest to that centre. The README explains that this avoids the crescent and enclave problems that a plain average would produce.
How do I build the japanese-addresses CSV and API myself?
Clone the repository, run npm install, then npm run build to download the source data and produce latest.csv, and npm run build:api to generate the JSON API from it. Optional scripts add the block level and residential display APIs.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/geolonia-japanese-addresses)Was this useful?