GeoThai python-library

Every province, district, subdistrict and postal code of Thailand, in one typed Python package with search.

👉 Website · 👉 Data and changelog

Features

• 77 provinces, 928 districts and 7,436 subdistricts with Thai and English names and DOPA codes
• Postal codes per subdistrict, and a lookup from a postal code to its subdistricts
• Search by Thai or English name, with or without spaces, hyphens or the word for the level
• Frozen dataclasses with a docstring on every field, and Literal types for every code
• Data loads on the first call, so import geothai stays fast
• No dependencies

Install

pip install geothai

The package needs Python 3.11 or later.

Usage

>>> from geothai import address, by_postal_code, districts, province, search, subdistricts
>>> province("84")
Province(code='84', name_th='สุราษฎร์ธานี', name_en='Surat Thani')
>>> len(districts("84"))
19
>>> [s.name_en for s in subdistricts("8405")]
['Ko Pha-ngan', 'Ban Tai', 'Ko Tao']
>>> [s.name_th for s in by_postal_code("84280")]
['เกาะพะงัน', 'บ้านใต้']
>>> a = address("840503")
>>> f"{a.subdistrict.name_th} {a.district.name_th} {a.province.name_th}"
'เกาะเต่า เกาะพะงัน สุราษฎร์ธานี'
>>> [f"{r.level} {r.area.name_th}" for r in search("phangan")]
['district เกาะพะงัน', 'subdistrict เกาะพะงัน']

API

Every function takes codes as strings and returns a new list. The areas are frozen dataclasses, so you can use them as dictionary keys.

The areas that DOPA abolished have their own module:

>>> from geothai.abolished import abolished_areas
>>> next(a for a in abolished_areas() if a.code == "100205").abolished_on
'2006-01-01'

Types

from geothai.types import Province, ProvinceCode, SearchResult, Subdistrict

The functions take str, not the code types. A data release can remove a code, and that must not break your type check in a patch update.

Versions

A new GeoThai/data release ships as a patch version. A change to the API gets a minor or major version. DATA_VERSION tells you which data you have. The changes in each data release are at geothai.fasu.dev/changelog.

Upgrading from v2

Version 3 is a rewrite on new data. Version 2 did not load its data after install, so code that used it did not run.

The v2 code is on the archive branch.

Why?

Address forms in Thailand need the same four lists, and most copies of them are old: merged postal codes, abolished subdistricts, English names on the wrong area. This package ships the data that GeoThai checks against official sources, with types your editor can read.

License

The code is MIT. The data is CC BY 4.0 © 2026 Pongsakorn Thipayanate.

If you show the data, credit "GeoThai".