japanese-address-parser-py

A Python toolkit for processing Japanese addresses

What is it?

japanese-address-parser-py is a Python package for parsing Japanese addresses. Any address can be parsed into structured data.

Installation from PyPI

pip install japanese-address-parser-py

Usage

Sequential execution

from japanese_address_parser_py import Parser

addresses = [
    "埼玉県さいたま市浦和区高砂3-15-1",
    "千葉県千葉市中央区市場町1-1",
    "東京都新宿区西新宿2-8-1",
    "神奈川県横浜市中区日本大通1",
]
parser = Parser()
for address in addresses:
    parse_result = parser.parse(address)
    print(parse_result.address)

{'prefecture': '埼玉県', 'town': '高砂三丁目', 'rest': '15-1', 'city': 'さいたま市浦和区'}
{'rest': '1-1', 'town': '市場町', 'prefecture': '千葉県', 'city': '千葉市中央区'}
{'prefecture': '東京都', 'rest': '8-1', 'town': '西新宿二丁目', 'city': '新宿区'}
{'town': '日本大通', 'city': '横浜市中区', 'prefecture': '神奈川県', 'rest': '1'}

Parallel execution

from concurrent.futures import ThreadPoolExecutor

from japanese_address_parser_py import Parser

addresses = [
    "徳島県徳島市万代町1-1",
    "香川県高松市番町4-1-10",
    "愛媛県松山市一番町4-4-2",
    "高知県高知市丸ノ内1-2-20",
]

parser = Parser()
with ThreadPoolExecutor(max_workers=4) as executor:
    results = executor.map(parser.parse, addresses)

for result in results:
    print(result.address)

{'prefecture': '徳島県', 'rest': '1', 'city': '徳島市', 'town': '万代町一丁目'}
{'prefecture': '香川県', 'city': '高松市', 'town': '番町四丁目', 'rest': '1-10'}
{'city': '松山市', 'rest': '4-2', 'town': '一番町四丁目', 'prefecture': '愛媛県'}
{'city': '高知市', 'town': '丸ノ内一丁目', 'rest': '2-20', 'prefecture': '高知県'}

Async usage

import asyncio
from japanese_address_parser_py import parse_async

ADDRESSES = [
    "神奈川県相模原市緑区西橋本五丁目3番21",
    "神奈川県相模原市中央区中央二丁目11番15号",
    "神奈川県相模原市南区相模大野五丁目31番1号",
]


async def main():
    tasks = [parse_async(addr) for addr in ADDRESSES]
    results = await asyncio.gather(*tasks)

    for result in results:
        print(result.address)
        print(result.error)


asyncio.run(main())

Development

This library is written in Rust. You need to set up a Rust development environment to build this library. We recommend uv for Python dependency management and development.

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone repository
git clone https://github.com/YuukiToriyama/japanese-address-parser.git
cd japanese-address-parser/python
# Setup environment and install dependencies
uv sync
# Run tests
uv run pytest tests/test_parser.py

If you want to build the wheel manually:

uv tool run maturin build --release --out dist

Support

This software is maintained by YuukiToriyama. If you have any questions, please create a new issue.

Where to get source code

The source code is hosted on GitHub at: https://github.com/YuukiToriyama/japanese-address-parser

Acknowledgements

This software was inspired by @geolonia/normalize-japanese-addresses.
In addition, the parsing process uses Geolonia 住所データ which is provided by 株式会社Geolonia.

License

This library is distributed under the terms of the MIT license.