# GeoThai

> A zero-dependency geographic data ecosystem for Thailand, with packages for TypeScript, Python, and raw JSON data covering provinces, districts, subdistricts, and postal codes.

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](https://github.com/GeoThai/npm-packages): A zero-dependency TypeScript package for Node.js, with typed lookup and filter functions. Published as [geothai](https://www.npmjs.com/package/geothai) on npm.
- [python-library](https://github.com/GeoThai/python-library): The same data and lookup functions for Python. Published as [geothai](https://pypi.org/project/geothai/) on PyPI.
- [data](https://github.com/GeoThai/data): The raw geographic data in four versions, from flat JSON files to an ultra-fast indexed lookup format.

## Usage

```typescript
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: "กรุงเทพมหานคร" });
```

```python
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](https://github.com/GeoThai) GitHub organization.