GeoThai is a small ecosystem of packages that give you structured geographic data for Thailand. It covers all provinces, districts, subdistricts, and postal codes, through a TypeScript package, a Python package, and a raw data repository.

The Packages

npm-packages: A zero-dependency TypeScript package for Node.js, with typed lookup and filter functions. Published as geothai on npm.
python-library: The same data and lookup functions for Python. Published as geothai on PyPI.
data: The raw geographic data in four versions, from flat JSON files to an ultra-fast indexed lookup format.

Usage

import {
  getAllProvinces,
  getProvinceByCode,
  getProvincesByCriterion,
} from "geothai";

// All provinces
const provinces = getAllProvinces();

// Single province by code (with auto-completion)
const bangkok = getProvinceByCode("10");

// Filter by Thai name
const filtered = getProvincesByCriterion({ name_th: "กรุงเทพมหานคร" });

from geothai import get_all_provinces, get_province_by_code, get_provinces_by_criterion

provinces = get_all_provinces()
province = get_province_by_code(10)
matching = get_provinces_by_criterion({"name_th": "กรุงเทพมหานคร"})

The Data Repository

The data repository stores the same source data in four versions:

v1: Separate flat JSON files for provinces, districts, and subdistricts.
v2: A nested structure that adds postal codes.
v3: Indexed mappings, built for fast programmatic lookups.
v4: An ultra-fast, denormalized format with embedded hierarchies.

Both the TypeScript and Python packages build on top of this data.

Stats

The npm package had more than 9,300 downloads in the past year.
The current npm release is v3.0.0, built with tsdown.
The npm package requires Node.js 20 or later.

Maintained under the GeoThai GitHub organization.