Thai Province Data

The data follows a strict hierarchical structure from the largest geographic area down to the smallest administrative division. You can navigate the data by following these relationships:

1. Geographies: The root level.
2. Provinces: Linked to Geographies via geography_id.
3. Districts: Linked to Provinces via province_id.
4. Sub-districts: Linked to Districts via district_id.

This One-to-Many (1..*) relationship allows you to drill down from a specific geography to its constituent provinces, then to their districts, and finally to their sub-districts.

The SubDistrict With District And Province schema defines a bottom-up hierarchical object where a SubDistrict includes its parent district, which in turn includes its parent province.

{
  "type": "object",
  "allOf": [
    { "$ref": "#/definitions/sub_district" },
    {
      "properties": {
        "district": {
          "allOf": [
            { "$ref": "#/definitions/district" },
            {
              "properties": {
                "province": { "$ref": "#/definitions/province" }
              }
            }
          ]
        }
      }
    }
  ]
}

The Province With District And SubDistrict schema defines a hierarchical object where a Province contains an array of districts, and each district contains an array of sub_districts.

{
  "type": "object",
  "allOf": [
    { "$ref": "#/definitions/province" },
    {
      "properties": {
        "districts": {
          "type": "array",
          "items": {
            "allOf": [
              { "$ref": "#/definitions/district" },
              {
                "properties": {
                  "sub_districts": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/sub_district" }
                  }
                }
              }
            ]
          }
        }
      }
    }
  ]
}

The data follows a strict hierarchical relationship (ERD) from largest to smallest administrative unit:

1. Geographies (Top level)
2. Provinces (Belong to Geographies)
3. Districts (Belong to Provinces)
4. Sub-districts (Belong to Districts)

Relationship mapping:

• GEOGRAPHIES 1 -> N PROVINCES
• PROVINCES 1 -> N DISTRICTS
• DISTRICTS 1 -> N SUB_DISTRICTS

erDiagram
  GEOGRAPHIES ||--o{ PROVINCES : "1..*"
  PROVINCES   ||--o{ DISTRICTS : "1..*"
  DISTRICTS   ||--o{ SUB_DISTRICTS : "1..*"

To run the data validation and export scripts locally, set up a Python virtual environment and install the required dependencies (pandas and openpyxl).

python3 -m venv .venv
source .venv/bin/activate
pip install -U pandas openpyxl

You can fetch the latest administrative data directly from the GitHub repository using the api/latest/ directory. Available endpoints include:

• province.json
• district.json
• sub_district.json
• province_with_district_and_sub_district.json
• sub_district_with_district_and_province.json

Use the raw GitHub URL to perform curl requests or fetch data in your application.

curl -s https://raw.githubusercontent.com/kongvut/thai-province-data/refs/heads/master/api/latest/province.json | jq '.[0]'

For integration into databases, data pipelines, or spreadsheets, you can use the files located in the formats/ directory. Supported formats include:

• CSV: Ideal for Excel or Google Sheets.
• SQL: Includes CREATE TABLE and INSERT statements for database seeding.
• XLSX: Requires pandas and openpyxl for programmatic processing.
• XML: For systems requiring XML structures.

The repository includes several scripts for validating data and exporting it into various formats. These are located in the scripts/ directory.

Available Scripts:

• scripts/0_validate_data.py: Validates data against JSON schemas, checks foreign key integrity, and verifies formats.
• scripts/1_export_file_format.py --overwrite: Exports data into CSV, JSON, SQL, XLSX, or XML formats.
• scripts/2_export_api.py --overwrite: Builds the JSON files used for the API endpoints.
• scripts/make.py: Runs the complete pipeline (validation through export).

If you prefer not to install Python or dependencies locally, use Docker Compose to run the validation or the full pipeline.

Commands:

• Build the image: docker compose build
• Run only validation: docker compose run --rm validate
• Run the full pipeline (validate → export formats → export API): docker compose run --rm make

Use the requests library to fetch the province JSON array from the GitHub Raw URL.

import requests

url = "https://raw.githubusercontent.com/kongvut/thai-province-data/refs/heads/master/api/latest/province.json"
provinces = requests.get(url).json()

print(provinces[0])
# Output example: {'id': 1, 'name_th': 'กรุงเทพมหานคร', 'name_en': 'Bangkok', 'geography_id': 2, ...}