kltng/chgis-tgaz

CHGIS TGAZ

Query the China Historical GIS Temporal Gazetteer for historical placenames and administrative units (222 BCE–1911 CE).

Critical: Things Claude Won't Know Without This Skill

The correct domain is chgis.hudci.org — the old maps.cga.harvard.edu is defunct. Do not use it.

ID lookups use a URL path format, NOT query params:

✅  https://chgis.hudci.org/tgaz/placename/json/hvd_32180
❌  https://chgis.hudci.org/tgaz/placename?id=hvd_32180&fmt=json

The ?fmt=json parameter only works for the faceted search endpoint.

TGAZ IDs use the hvd_ prefix: CHGIS ID 32180 → TGAZ ID hvd_32180.

The ipar (parent) search parameter is unreliable. For hierarchical queries (e.g., "find all counties in Zhejiang"), use the canonical record drill-down approach instead: look up the parent record by ID and read its subordinate units.

Romanization quirks: Some names use older romanizations, not modern pinyin. For example, Ningbo is stored as "Ningpo". If a search returns no results, try alternative romanizations.

Search uses prefix matching: n=beijing matches 北京路, 北京行省, 北井县, etc. Short terms return more results.

Python Script

Use scripts/tgaz_api.py for programmatic access (zero dependencies):

from scripts.tgaz_api import TGAZAPI
api = TGAZAPI()

# Faceted search
results = api.search("suzhou", year=1820)
results = api.search("北京", feature_type="fu")

# ID lookup (correct URL format handled automatically)
record = api.get_by_id("hvd_32180")

# Extract structured data
name = api.get_name(record)                    # Chinese name
transcription = api.get_transcription(record)  # Romanized
begin, end = api.get_temporal_span(record)     # Year range
modern = api.get_modern_location(record)       # Present-day equivalent
ftype = api.get_feature_type(record)           # Administrative type
subs = api.get_subordinates(record)            # Child units (reliable!)

# Formatted summary
print(api.summarize(record))

Quick Reference

Faceted search:

https://chgis.hudci.org/tgaz/placename?n=suzhou&yr=1820&fmt=json

Parameters:

• n — placename (Chinese or Romanized, required)
• yr — historical year (-222 to 1911)
• ftyp — administrative type: xian (县), fu (府), zhou (州), sheng (省), dao (道), lu (路), jun (郡)
• ipar — parent unit (⚠️ unreliable — prefer canonical record drill-down)
• fmt — output format (json recommended; default is XML)

ID lookup (format in URL path):

• /placename/json/{id} — JSON
• /placename/xml/{id} — XML
• /placename/rdf/{id} — RDF

Hierarchical Queries (Recommended Approach)

Since ipar is unreliable, use this pattern for "find all X in Y" queries:

1. Search for the parent region to get its TGAZ ID
2. Look up the parent's canonical record via /placename/json/{id}
3. Read the historical_context.has parts field for subordinate units
4. Filter subordinates by year range and feature type

api = TGAZAPI()
# Find Zhejiang
results = api.search("zhejiang", year=1850, feature_type="sheng")
zhejiang_id = results[0]["sys_id"]  # e.g., hvd_30015

# Get canonical record with subordinates
record = api.get_by_id(zhejiang_id)
subordinates = api.get_subordinates(record)

# Filter to active units in 1850
for sub in subordinates:
    # Check temporal range overlaps with 1850
    ...

Encoding

• Pass Chinese characters as UTF-8 directly: "n": "北京" ✅
• Do not URL-encode Chinese into hex ❌
• URL-encode spaces and special characters normally

Related Skills

• cbdb-api: Cross-reference CBDB address data with TGAZ placenames to map historical figures to locations
• wikidata-search: Find Wikidata entries for historical places identified in TGAZ

Resources

• references/api_reference.md — Complete endpoint specs, all parameters, response field details
• scripts/tgaz_api.py — Python client with correct URL handling and hierarchical query support