Thai Address Universal is a library developed from thai-address-database, rewritten to fully support usage with TypeScript 🖥️✨. This allows for efficient use and ensures accurate type-checking ✅.

This library includes various functions that assist in searching for address data in Thailand 🇹🇭 from multiple types, and it can also extract address information from a full address string conveniently and accurately 🏠🔍.

🛠️ Installation

npm install thai-address-universal --save

<script src="https://cdn.jsdelivr.net/npm/thai-address-universal/dist/umd/index.js"></script>

👨‍💻 Example

import { getProvinceAll } from 'thai-address-universal';
const getProvince = async () => {
    const provinces = await getProvinceAll();
    console.log(provinces);
};
getProvince();

<script src="https://cdn.jsdelivr.net/npm/thai-address-universal/dist/umd/index.js"></script>
<script>
    const getProvince = async () => {
        const provinces = await ThaiAddressUniversal.getProvinceAll();
        console.log(provinces);
    };
    getProvince();
</script>

✨ Features

getDatabase (): IExpanded[]

getGeoMode (): boolean

setGeoMode (status: boolean): Promise<void>

getEngMode (): boolean

setEngMode (status: boolean): Promise<void>

getProvinceAll (): Promise<string[]>

getDistrictByProvince (province: string): Promise<string[]>

getSubDistrictByDistrict (district: string): Promise<string[]>

getPostalCodeBySubDistrict (sub_district: string): Promise<string[]>

searchAddressByProvince (searchStr: string, maxResult?: number): Promise<IExpanded[]>

searchAddressByDistrict (searchStr: string, maxResult?: number): Promise<IExpanded[]>

searchAddressBySubDistrict (searchStr: string, maxResult?: number): Promise<IExpanded[]>

searchAddressByPostalCode (searchStr: string | number, maxResult?: number): Promise<IExpanded[]>

splitAddress (fullAddress: string): Promise<IExpanded | null>

translateWord (word: string): Promise<string>

🆕 New in v2.2.0

Structured directory

Returns entries carrying both languages and the official geocode (AddressEntry = { nameTh, nameEn, code, postalCode? }), independent of the global setEngMode / setGeoMode switches. Every function accepts the parent's Thai name, English name, or numeric code.

getProvinces (): Promise<AddressEntry[]>

All 77 provinces — e.g. { nameTh: 'เชียงใหม่', nameEn: 'Chiang Mai', code: '50' }.

getDistricts (province: string): Promise<AddressEntry[]>

Districts of province (given as a name in either language, or a 2-digit code).

getSubDistricts (district: string): Promise<AddressEntry[]>

Sub-districts of district, each including its postalCode.

getByGeocode (code: string): Promise<AddressEntry | null>

Looks up a single unit by its exact geocode; the length of code (2 / 4 / 6) selects the level. null for an unknown code.

Validation

validateAddress (
    input: { province?; district?; subDistrict?; postalCode? },
    options?: { language?: 'thai' | 'eng' },
): Promise<{ valid: boolean; errors: Record<string, string>; match?: IExpanded }>

Checks that the given parts exist and belong together (a district that sits in the province, a postal code that serves the sub-district, …). Only the fields you pass are checked, so it works on a partially filled form; the chain stops at the first inconsistent field and names it in errors.

await validateAddress({ province: 'เชียงใหม่', district: 'หาดใหญ่' });
// { valid: false, errors: { district: 'District "หาดใหญ่" is not in province "เชียงใหม่"' } }

Formatting

formatAddress (
    parts: { address?; subDistrict?; district?; province?; postalCode? },
    options?: { language?: 'thai' | 'eng'; prefix?: boolean; separator?: string },
): string

The inverse of splitAddress — assembles one address string (synchronous, no data load). Blank parts are skipped; Bangkok automatically switches to แขวง / เขต and drops the province word.

formatAddress({
    address: '99/9',
    subDistrict: 'ศรีภูมิ',
    district: 'เมืองเชียงใหม่',
    province: 'เชียงใหม่',
    postalCode: '50200',
});
// "99/9 ตำบลศรีภูมิ อำเภอเมืองเชียงใหม่ จังหวัดเชียงใหม่ 50200"

Warm-up

preload (options?: { language?: 'thai' | 'eng' | 'both'; geo?: boolean }): Promise<void>

Fetches the data chunks ahead of time so the first real lookup does not wait on the network. Never changes the active language or geo mode — e.g. call it when an address form mounts.

Full per-symbol API reference (generated from the source): https://ophoomo.github.io/thai-address-universal/ — see also llms.txt for a condensed, example-heavy overview.

🙏 Acknowledgements

I would like to extend my deepest thanks to:

• Sellsuki thai-address-database

• Bangmod Cloud thai-address-database

• Earthchie jquery.Thailand.js

Your contributions, whether big or small, have made this project what it is today. Thank you for your support and inspiration! 🎉

🤝 Contact

📧 For questions or support, please reach out to us at [email protected].

Thank you for using Thai Address Universal! We hope you find it useful and look forward to your contributions. 🙌