Thai Address Data

A TypeScript/JavaScript library providing Thailand's address data including districts, sub-districts, and provinces with postal code reference.

Demo

https://thai-data.vercel.app

Features

• 📦 TypeScript Support: Full type definitions included
• 🚀 ES Modules & CommonJS: Works with both import and require
• 🔍 Multiple Query Methods: Search by postal code, district, sub-district, etc.
• 📏 Lightweight: Only includes essential data
• 🛠 Well-Tested: Comprehensive test coverage

Installation

npm install thai-data
# or
yarn add thai-data

Usage

TypeScript / ES Modules

import {
  getAddressByZipCode,
  getSubdistrictsByZipCode,
  getDistrictsByZipCode,
  getProvinceByZipCode,
  getAddressSuggestions,
  getAllAddressData,
} from "thai-data";

// Get all data for a specific postal code
const addressData = getAddressByZipCode("10110");

// Get sub-district names for a postal code
const subDistricts = getSubdistrictsByZipCode("10110");

// Get district names for a postal code
const districts = getDistrictsByZipCode("10110");

// Get province name for a postal code
const province = getProvinceByZipCode("10110");

// Get address suggestions
const suggestion = getAddressSuggestions("10110", "บางรัก");

// Get all address data
const allData = getAllAddressData();

CommonJS

const {
  getAddressByZipCode,
  getSubdistrictsByZipCode,
  getDistrictsByZipCode,
  getProvinceByZipCode,
  getAddressSuggestions,
  getAllAddressData,
} = require("thai-data");

const addressData = getAddressByZipCode("10110");
console.log(addressData);

API Reference

getAddressByZipCode(zipCode: string | number): ZipCodeData | null

Get complete address data for a specific postal code.

getSubdistrictsByZipCode(zipCode: string | number): string[]

Get all sub-district names for a given postal code.

getDistrictsByZipCode(zipCode: string | number): string[]

Get all district names for a given postal code.

getProvinceByZipCode(zipCode: string | number): string | null

Get the province name for a given postal code.

getAddressSuggestions(zipCode: string | number, subDistrict?: string): AddressSuggestion

Get address suggestions based on postal code and optional sub-district.

getAllAddressData(): ZipCodeData[]

Get all address data.

Type Definitions

interface SubDistrict {
  subDistrictId: string;
  districtId: string;
  provinceId: string;
  subDistrictName: string;
}

interface District {
  districtId: string;
  proviceId: string;
  districtName: string;
}

interface Province {
  provinceId: string;
  provinceName: string;
}

interface ZipCodeData {
  zipCode: string;
  subDistrictList: SubDistrict[];
  districtList: District[];
  provinceList: Province[];
}

interface AddressSuggestion {
  subDistrict: string | string[] | null;
  districtName: string | null;
  provinceName: string | null;
  zipCode: string | null;
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Install dependencies:

   npm install

3. Make your changes
4. Run tests:

   npm test

5. Submit a pull request

Migration from v2 to v3

In v3, we've updated the function names to be more descriptive and consistent. Here's how to migrate from v2 to v3:

v2	v3	Description
getDataForZipCode	getAddressByZipCode	Get complete address data for a postal code
getSubDistrictNames	getSubdistrictsByZipCode	Get sub-district names for a postal code
getDistrictNames	getDistrictsByZipCode	Get district names for a postal code
getProvinceName	getProvinceByZipCode	Get province name for a postal code
getAutoSuggestion	getAddressSuggestions	Get address suggestions
getAllData	getAllAddressData	Get all address data

Example Migration

// v2
const {
  getDataForZipCode,
  getSubDistrictNames,
  getDistrictNames,
  getProvinceName,
  getAutoSuggestion,
  getAllData,
} = require("thai-data");

// v3
const {
  getAddressByZipCode,
  getSubdistrictsByZipCode,
  getDistrictsByZipCode,
  getProvinceByZipCode,
  getAddressSuggestions,
  getAllAddressData,
} = require("thai-data");

Examples

Get Address by Zip Code

import { getAddressByZipCode } from 'thai-data';

const addressData = getAddressByZipCode('10110');

console.log(addressData);
{
  zipCode: '10110',
  subDistrictList: [
    { subDistrictId: '100101', districtId: '1001', provinceId: '10', subDistrictName: 'พระบรมมหาราชวัง' },
    // ... more sub-districts
  ],
  districtList: [
    { districtId: '1001', provinceId: '10', districtName: 'พระนคร' },
    // ... more districts
  ],
  provinceList: [
    { provinceId: '10', provinceName: 'กรุงเทพมหานคร' }
  ]
}

Get Address Suggestions

import { getAddressSuggestions } from 'thai-data';

// Get suggestions with just zip code
const suggestions = getAddressSuggestions('10110');
console.log(suggestions);
{
  subDistrict: [...], // Array of all sub-districts for this zip code
  districtName: '...', // Single district name if only one exists
  provinceName: '...', // Province name
  zipCode: '10110'
}

// Get suggestions with zip code and sub-district filter
const filteredSuggestions = getAddressSuggestions('10110', 'บางรัก');
console.log(filteredSuggestions);
{
  subDistrict: 'บางรัก', // Matching sub-district name
  districtName: 'บางรัก', // District name
  provinceName: 'กรุงเทพมหานคร', // Province name
  zipCode: '10500' // Matching zip code
}

Get All Address Data

import { getAllAddressData } from "thai-data";

const allAddresses = getAllAddressData();
console.log(`Total zip codes: ${allAddresses.length}`);
// Output: Total zip codes: [number of zip codes]