jp-address-parser

A simple parser for Japanese street address.

This module works by matching prebuilt city data against the input address. The Japan city data is downloaded from HeartRails Geo API on the fly.

Install

npm i jp-address-parser

Usage

Basic Usage

const japa = require('jp-address-parser');

console.log(await japa.parse('東京北区東十条6丁目二 十八番七〇'))
/*
{ prefecture: '東京都',
  city: '北区',
  town: '東十条',
  chome: 6,
  ban: 28,
  go: 70,
  left: '' }
*/
console.log(await japa.normalize('京都府京都市東山区本町22-489-1'))
// 京都府京都市東山区本町二十二丁目４８９番１号

In this example, the list of cities in 東京都, and the list of towns in 北区 are downloaded. By default, the data is stored at ./data/town_map.json and can be changed.

See test for a list of supported address syntax.

Configuration

const japa = require('jp-address-parser')(data_path, axios_config);

• data_path: the place to store the downloaded data.
• axios_config: additional config to pass to axios

API

parse

async function parse (address_text, options)

• address_text: the address to parse
• options: object, optional
  • prefecture: assumption of the address_text
  • city: assumption of the address_text
  • town: assumption of the address_text

Parsed result is an object containing the following properties.

• prefecture: one of the 47 prefectures
• city: such as 千代田区 or 塩谷郡高根沢町. The data obtained from HeartRails Geo API supports only three layers segementation.
• town: such as 東十条
• chome, ban, go: the 丁目-番-号 part of address. Note that the parsed numbers can be different from what it actually means. Also, 番 and 番地 are not distinguished here for simplicity.
• left: what's left

normalize

async function normalize(address_text, options)

Normalize address text so that two addresses can be compared.

• options: also passed to parse function
  • number_scheme:
    • classic: 東京都調布市入間町十三丁目２８番７０号 (default)
    • numeric: 東京都調布市入間町13-28-70
    • chome_full_width: 京都府京都市東山区本町２２丁目４８９−１
    • chome_numeric: 東京都千代田区東神田3丁目1-9
    • chome_ban_numeric: 東京都国分寺市高木町1丁目6番32

load_data

async function load_data(prefecture, city, { skip_existing = true, recursive = false, verbose = false } = {})

This function allows downloading the city data to data_path before parsing.

• load_data(prefecture): download city list in the prefecture
• load_data(prefecture, city): download the town list in the (prefecture, city)
• load_data(prefecture, null, { recursive: true }): download all city, town lists in the prefecture
• load_data(prefecture, city, { skip_existing: false }): force updating data (otherwise, skip downloaded cities, towns)
• load_data(prefecture, city, { verbose: true }): show download process in STDOUT