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, match, 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 เกาะพะงัน']
>>> match("ต.ตลาด", district="อ.เมือง", province="สุราษฎร์ธานี")[0].subdistrict.code
'840101'

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.

match() is for addresses typed by hand, such as old records or form input. It reads short forms such as ต., อ. and จ., the word เมือง for a capital district, and กทม for Bangkok. Names must match in full. One result means the address is clear. More than one means you need another argument: 795 subdistrict names are used more than once. None means no current subdistrict has the name.

The areas that DOPA abolished have their own module:

>>> from geothai.abolished import abolished_areas
>>> bang_na = next(a for a in abolished_areas() if a.code == "104701")
>>> bang_na.abolished_on
'2022-04-22'
>>> bang_na.successors
('104702', '104703')
>>> bang_na.successors_basis
'notice'

successors lists the codes that took an abolished area's place. successors_basis says how sure the link is: "notice" comes from a Royal Gazette notice, with the date and source in successors_in_force and successors_source. "name" is a match by Thai name for codes DOPA dropped in 2006, likely but not proven. When no successor is known, successors is empty.

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". Source credits and the license of thailand-geography-json are in NOTICE.