vn-address-converter

A Node.js library for parsing and converting Vietnamese addresses.

• Parses free-text Vietnamese address strings into structured components (street, ward, district, province)
• Converts old administrative addresses to the new post-2025 format (removes district level)
• Resolves address components to VNCDC province (TINH_ID) and ward (XA_ID) IDs

Installation

npm install vn-address-converter

API

parseAddress(addressString) → Address

Splits a comma/semicolon/pipe/hyphen-separated address string into components.

const { parseAddress } = require("vn-address-converter");

parseAddress("Phường Bến Thành, Quận 1, Thành phố Hồ Chí Minh");
// Address { ward: 'Phường Bến Thành', district: 'Quận 1', province: 'Thành phố Hồ Chí Minh' }

parseAddress("123 Nguyễn Huệ, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh");
// Address { streetAddress: '123 Nguyễn Huệ', ward: 'Phường Bến Nghé', district: 'Quận 1', province: '...' }

Supported formats: | Parts | Interpretation | |---|---| | district, province | 2-part | | ward, district, province | 3-part | | street, ward, district, province | 4-part | | street part1, street part2, …, ward, district, province | 5+-part |

convertToNewAddress(address) → Address

Converts a pre-2025 address (with district) to the new post-2025 format (district removed, ward/province updated).

const { convertToNewAddress, Address } = require("vn-address-converter");

const old = new Address({
  ward: "Phường 12",
  district: "Quận Gò Vấp",
  province: "Thành phố Hồ Chí Minh",
});

convertToNewAddress(old);
// Address { ward: 'Phường An Hội Tây', district: null, province: 'Thành phố Hồ Chí Minh' }

Throws MappingMissingError if a component cannot be found in the mapping data.

parseAddressToIds(addressString) → { wardId, provinceId } | null

Full pipeline: parse the string then resolve to VNCDC IDs.

const { parseAddressToIds } = require("vn-address-converter");

parseAddressToIds("Phường Giảng Võ, Hà Nội");
// { wardId: 1016012, provinceId: 101 }

parseAddressToIds("p4n2, TT ĐHSP Tổ 8, Phường Cầu Giấy, Hà Nội");
// { wardId: 1016004, provinceId: 101 }

Returns null if parsing fails or the ward/province cannot be resolved.

findProvinceId(name) → number | null

Look up a TINH_ID from a province display name (accent-insensitive).

const { findProvinceId } = require("vn-address-converter");

findProvinceId("Khánh Hòa"); // 511
findProvinceId("TP Hồ Chí Minh"); // 701
findProvinceId("Hà Nội"); // 101

findWardId(name, provinceId?) → number | null

Look up an XA_ID from a ward display name, optionally scoped to a province.

const { findWardId } = require("vn-address-converter");

findWardId("Phường Giảng Võ", 101); // 1016012
findWardId("Giảng Võ"); // 1016012

normalizeAlias(name, level) / getAliases(name, level)

Low-level helpers used internally by the converter.

const {
  normalizeAlias,
  getAliases,
  AddressLevel,
} = require("vn-address-converter");

normalizeAlias("Quận Gò Vấp", AddressLevel.DISTRICT); // 'gò vấp'
getAliases("Quận 1", AddressLevel.DISTRICT); // ['1', 'quận 1', 'quan 1']

Classes & Constants

Address

new Address({ streetAddress, ward, district, province });
address.format(); // → "street, ward, district, province"

AddressLevel

AddressLevel.PROVINCE; // 'province'
AddressLevel.DISTRICT; // 'district'
AddressLevel.WARD; // 'ward'
AddressLevel.STREET; // 'street'

MappingMissingError

try {
  convertToNewAddress(addr);
} catch (e) {
  if (e instanceof MappingMissingError) {
    console.log(e.level, e.value); // e.g. 'province', 'Unknown City'
  }
}

License

MIT