thai-geolocate

English:

Node.js library for geographic matching in Thailand. This library provides functions to determine administrative area in Thailand—province, amphoe (district), and tambon (sub-district)—based on latitude and longitude inputs.

ไทย:

Node.js library ที่สามารถระบุ จังหวัด อําเภอ และตําบลในประเทศไทย จากตัวเลขพิกัด (coordinate) ค่าละติจูดและลองจิจูด (latitude, longtitude)

Features / ความสามารถ

English:

• findProvince: Identify the Thai province from the given coordinates.
• findAmphoe: Identify the district (amphoe) and its corresponding province.
• findTambon: Identify the sub-district (tambon) along with its amphoe and province.
• Accepts an optional accuracyLevel parameter to configure the precision of geographic matching.
• Validates coordinate inputs to ensure they fall within acceptable ranges.

ไทย:

• findProvince: หาจังหวัดจากค่า ละติจูด, ลองจิจูด
• findAmphoe: หาอําเภอและจังหวัด จากค่า ละติจูด, ลองจิจูด
• findTambon: หาตําบล,อําเภอ,และจังหวัดจากค่า ละติจูด, ลองจิจูด
• รองรับพารามิเตอร์ accuracyLevel หากต้องการปรับความแม่นยำของการจับคู่ข้อมูลภูมิศาสตร์ใน dataset
• ตรวจสอบความถูกต้องของค่า ละติจูด และ ลองจิจูด เพื่อให้แน่ใจว่าเป็นค่าพิกัดจริง

Installation / การติดตั้ง

Install the library via npm / ติดตั้งผ่าน npm:

npm install thai-geolocate

Or add it as a dependency in your package.json / หรือใส่เป็น dependency ใน package.json:

Don't forget to update the version number / อย่าลืมเปลื่ยนเลข version number

{
  "dependencies": {
    "thai-geolocate": "^1.0.2"
  }
}

Usage / วิธีใช้งาน

Import the functions in your Node.js project:

import { findProvince, findAmphoe, findTambon } from 'thai-geolocate';

const lat = 13.7563;
const lng = 100.5018;

// Example: Find Province / ตัวอย่าง: ค้นหาจังหวัด
const provinceResult = await findProvince(lat, lng);
console.log('Province:', provinceResult.province);

// Example: Find Amphoe / ตัวอย่าง: ค้นหาอําเภอ
const amphoeResult = await findAmphoe(lat, lng);
console.log('Amphoe:', amphoeResult.amphoe);
console.log('Province:', amphoeResult.province);

// Example: Find Tambon / ตัวอย่าง: ค้นหาตําบล
const tambonResult = await findTambon(lat, lng);
console.log('Tambon:', tambonResult.tambon);
console.log('Amphoe:', tambonResult.amphoe);
console.log('Province:', tambonResult.province);

Optional Accuracy Configuration

English:

Each function accepts an optional accuracyLevel parameter. By default, each of the properties in accuracyLevel is set to 1, which is the simplest but computes the fastest.

Higher accuracy level gives more precision, but may take longer to compute. Currently, the recommended combination for general use is { province: 1, amphoe: 1, tambon: 2 }

As of the latest version, only accuracyLevel 1 and 2 is available.

ไทย:

แต่ละฟังก์ชันสามารถรับพารามิเตอร์ accuracyLevel ที่เป็นตัวเลือกได้ โดยค่าเริ่มต้นจะตั้งค่าระดับความแม่นยำไว้ที่ 1 ซึ่งเป็นระดับที่เรืยบง่ายที่สุดแต่ประมวลผลได้เร็วที่สุด

การตั้งค่าระดับความแม่นยำที่สูงขึ้นจะทําให้ผลลัพธ์แม่นยำมากขึ้น แต่อาจใช้เวลาประมวลผลนานกว่า การตั้งค่าที่แนะนำสำหรับการใช้งานทั่วไปคือ { province: 1, amphoe: 1, tambon: 2 }

สำหรับเวอร์ชันล่าสุดนี้ มีเฉพาะ accuracyLevel 1 และ 2 เท่านั้นที่ใช้ได้

import { findProvince, findAmphoe, findTambon } from 'thai-geolocate';

// Example: Find Tambon / ตัวอย่าง: ค้นหาตําบล
const lat = 13.599302;
const lng = 100.369061;
const accuracyConfig = { 
    province: 1, 
    amphoe: 1,
    tambon: 2
}

const tambonResult = await findTambon(lat, lng, accuracyConfig);

console.log('Tambon:', tambonResult.tambon);
console.log('Amphoe:', tambonResult.amphoe);
console.log('Province:', tambonResult.province);

Note: The accuracyLevel parameter should be an object with numeric values (e.g., { province: 1 }). Passing an incorrect type or out-of-range values will result in an error.

หมายเหตุ: พารามิเตอร์ accuracyLevel ต้องเป็น object ที่มีค่าเป็นตัวเลขเท่านั้น (เช่น { province: 1 }) หากส่งข้อมูลประเภทผิดหรือค่าไม่ตรงตามช่วงที่กำหนด ระบบจะแสดงข้อผิดพลาด

API Reference / วิธีใช้ API

findProvince(lat, lng, [accuracyLevel])

• Parameters:
  • lat (number): Latitude (-90 to 90).
  • lng (number): Longitude (-180 to 180).
  • accuracyLevel (object, optional): Example: { province: 1 }
• Returns: An object with a province property containing details:
  • nameEN: English name.
  • nameTH: Thai name.
  • pcode: Province code.
  • admLevel: Administrative level (e.g., "ADM1").

findAmphoe(lat, lng, [accuracyLevel])

• Parameters:
  • lat (number): Latitude (-90 to 90).
  • lng (number): Longitude (-180 to 180).
  • accuracyLevel (object, optional): Example: { province: 1, amphoe: 1 }
• Returns: An object containing the following, each containing details in the format of province above:
  • province: Province details.
  • amphoe: District details.

findTambon(lat, lng, [accuracyLevel])

• Parameters:
  • lat (number): Latitude (-90 to 90).
  • lng (number): Longitude (-180 to 180).
  • accuracyLevel (object, optional): Example: { province: 1, amphoe: 1, tambon: 1 }
• Returns: An object containing the following, each containing details in the format of province above:
  • province: Province details.
  • amphoe: District details.
  • tambon: Sub-district details.

Note: The functions are async. Use await (or .then()).

หมายเหตุ: ฟังก์ชันใช้ async โปรดใช้ await (หรือ .then())

Testing / การทดสอบ

English:

This library comes with a comprehensive test suite using Jest. To run the tests:

ไทย:

ขั้นตอนการทดสอบทำได้โดยใช้ Jest

1. Install Jest as a dev dependency:

   npm install --save-dev jest

2. Run the tests:

   npm test

Contributing / การมีส่วนร่วม

Contributions are welcome! Please read our CONTRIBUTING.md for guidelines on how to contribute to this project.

หากท่านต้องการ contribute สามารถอ่านมาตรการได้ที่ CONTRIBUTING.md

License / ใบอนุญาต

This project is licensed under the MIT License. See the LICENSE file for details.

Contact / ติดต่อ

For any questions or suggestions, please open an issue on https://github.com/Atiwat-R/thai-geolocate or contact [email protected]

Author

Atiwat Rachatawarn - อธิวัฒน์ รัชตะวรรณ - [email protected] - https://github.com/Atiwat-R/thai-geolocate