API Reference

search(query, options?)

ค้นหาชื่อพื้นที่ด้วยภาษาไทย ภาษาอังกฤษ หรือ alias และคืน SearchResult[] ถ้าไม่พบจะคืน []

import { search } from "thai-address-sdk";

const results = search("อยูทยา", {
  levels: ["province"],
  limit: 5,
  minScore: 0.72,
  format: "full_th",
});

อ่านผลลัพธ์

แต่ละรายการมี type, province, formattedAddress และ match ส่วน district, subdistrict และ postalCode ขึ้นอยู่กับระดับพื้นที่ที่พบ

const [result] = search("อยูทยา", { levels: ["province"] });

if (result) {
  console.log(result.formattedAddress);
  console.log(result.match.matchType);
  console.log(result.match.corrected);
  console.log(result.match.confidence);
}

matchType มี exact, alias, prefix, contains และ fuzzy โดย confidence อยู่ระหว่าง 0–1 เป็นคะแนนจัดอันดับภายใน SDK ไม่ใช่เปอร์เซ็นต์ความถูกต้อง

normalizeAddress(input, options?)

วิเคราะห์ข้อความที่มีหลายส่วน โดยใช้ความสัมพันธ์จังหวัด–อำเภอ–ตำบลช่วยเลือกคำตอบ คืนค่า NormalizeResult

import { normalizeAddress } from "thai-address-sdk";

const result = normalizeAddress("ต สุเทพ อ เมือง จ เชียงใหม่", {
  format: "short_th",
  limit: 5,
  minScore: 0.72,
});

const candidates = result.bestMatch
  ? [result.bestMatch, ...result.alternatives]
  : [];

ตัวเลือก format และ minScore มีค่าเริ่มต้นเหมือน search ส่วน limit คือจำนวน candidate ที่ใช้พิจารณา เริ่มต้น 5 และสูงสุด 20

ฟิลด์ผลลัพธ์ประกอบด้วย input, normalizedInput, status, bestMatch, confidence, alternatives และ corrections โดย bestMatch อาจเป็น null

Filter & lookup

ดึงรายการหรือค้นหารายการเดียวด้วยรหัสพื้นที่ เหมาะกับฟอร์มที่มี dropdown ต่อเนื่อง

getDistricts() และ getSubdistricts() เรียกโดยไม่ส่ง options เพื่อดึงทุกรายการได้ หากส่งตัวกรองที่ไม่มีข้อมูลจะคืนอาร์เรย์ว่าง

import { getSubdistricts, getProvince } from "thai-address-sdk";

const subdistricts = getSubdistricts({
  provinceCode: 14,
  districtCode: 1406,
});

const province = getProvince(999);
// undefined

ค้นด้วยรหัสไปรษณีย์ได้โดยกรองชุดข้อมูลตำบล ไม่ควรสมมติว่ารหัสไปรษณีย์หนึ่งค่ามีเพียงตำบลเดียว

const matches = getSubdistricts().filter(
  (item) => item.postalCode === 13160,
);

formatAddress(address, format?)

รับ object ที่มี province และมี district / subdistrict ตามต้องการ แล้วคืนข้อความที่อยู่ โดยไม่ต่อรหัสไปรษณีย์ให้อัตโนมัติ

import { formatAddress, getProvince } from "thai-address-sdk";

const province = getProvince(14);
if (province) {
  formatAddress({ province }, "full_th"); // จังหวัดพระนครศรีอยุธยา
  formatAddress({ province }, "short_th"); // จ.พระนครศรีอยุธยา
  formatAddress({ province }, "plain_th"); // พระนครศรีอยุธยา
  formatAddress({ province }, "en"); // Phra Nakhon Si Ayutthaya
}

กรุงเทพมหานครจะใช้คำนำหน้า “เขต” และ “แขวง” ตามพื้นที่ ส่วนจังหวัดอื่นใช้ “อำเภอ” และ “ตำบล”

TypeScript types & text helpers

import type {
  Province, District, Subdistrict,
  AddressHierarchy, AddressFormat, AddressLevel,
  SearchOptions, SearchResult,
  NormalizeOptions, NormalizeResult, NormalizeStatus,
  FilterOptions, MatchMetadata, MatchType, Correction,
} from "thai-address-sdk";

provinceCode เป็นรหัส 2 หลัก, districtCode 4 หลัก และ subdistrictCode 6 หลัก ทั้งหมดเป็นตัวเลข ใช้รหัสเหล่านี้แทนชื่อเป็น key ของรายการ

มี text helpers สำหรับงานเฉพาะทาง ได้แก่ normalizeText(text), stripAddressLabels(text) และ damerauLevenshtein(a, b) ดูรายละเอียดใน source code

ขอบเขตและข้อจำกัด

• รองรับจังหวัด อำเภอ/เขต ตำบล/แขวง และรหัสไปรษณีย์ ยังไม่แยกบ้านเลขที่ อาคาร ถนน ซอย หรือพิกัด
• Dataset เป็น snapshot ที่มากับแพ็กเกจ ไม่อัปเดตจากอินเทอร์เน็ตอัตโนมัติ
• Alias ยังไม่ครอบคลุมชื่อเรียกท้องถิ่นทั้งหมด และ fuzzy search อาจได้คำตอบที่ไม่ตรงกับเจตนา
• ผลลัพธ์ที่แก้คำสะกดหรือมีหลายคำตอบควรให้ผู้ใช้ตรวจสอบก่อนบันทึก
• SDK มีข้อมูลในตัวและประมวลผลแบบ synchronous ควรใช้ dynamic import และ debounce สำหรับหน้าเว็บ โดยทดสอบกับอุปกรณ์เป้าหมาย
• REST API ยังอยู่ในแผนงาน เวอร์ชันนี้ใช้ SDK ที่ติดตั้งในแอป

ข้อมูลและ License

SDK เผยแพร่ภายใต้ MIT License ชุดข้อมูลอ้างอิงจาก thailand-geography-json โดย Joe Takara ภายใต้ MIT เช่นกัน

Source commit ที่ระบุในแพ็กเกจ: b8b3fb91c7df1129ff5b43cb46f7fcffadd2156b

อ่าน ข้อความ License และ attribution ที่มากับเว็บไซต์ หากพบข้อมูลคลาดเคลื่อนสามารถ แจ้งปัญหาบน GitHub พร้อมชื่อพื้นที่และตัวอย่างที่ค้นหา