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. A record lists only the next level down. A province lists prefectures, not counties, so counties need a second step (see "Hierarchical Queries").

Romanization quirks: Some names use older romanizations, not modern pinyin. For example, Ningbo is stored as "Ningpo". Some names also have a space between syllables: 苏州 from 589 to 1112 is "Su Zhou", while 苏州府 is "Suzhou Fu". So n=suzhou&yr=1100 returns 0 results, and n=su zhou&yr=1100 returns 4. Search with Chinese characters when you can: 蘇州 and 苏州 both work. If a romanized search returns nothing, try a space between syllables and other romanizations.

Duplicate POLYGON records with longitude 0. Many places have a second record with "object type": "POLYGON" (often an hvd_90xxx id). Its xy coordinates has longitude 0 (sometimes 1-5), e.g. hvd_90496 苏州 0.00000, 31.276870. A few other records are 0.00000, 0.00000. On a map these points land near Africa. Before mapping, drop them: api.search(..., drop_bad_coords=True), or check api.has_bad_coords(result). Use the POINT record of the same place instead.

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")
results = api.search("蘇州", drop_bad_coords=True)   # for maps: no longitude-0 rows

# ID lookup (correct URL format handled automatically)
record = api.get_by_id("hvd_32180")
xml_text = api.get_by_id("hvd_32180", fmt="xml")  # xml/rdf return raw text

# 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)            # Direct child units only (one level)
units = api.get_descendants("hvd_30015", year=1850, levels=2)  # Two levels down

# 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.subordinate units field (each entry has child id, name, transcribed, begin_year, end_year)
4. Filter subordinates by year range
5. Repeat steps 2-4 for each child if you need the next level down

A record lists only its direct children. Zhejiang (hvd_30015) in 1850 lists 12 units: 11 prefectures (府) and 定海厅. It lists no counties. To get the counties, look up each of those 12 records too. Tested 2026-10-26: this gives 77 units at the second level, 75 of them counties (县).

get_descendants() does both levels for you. It makes one request per record (13 for Zhejiang), at most one per second.

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

# Level 1 only: prefectures
record = api.get_by_id(zhejiang_id)
for sub in api.get_subordinates(record):
    if int(sub["begin_year"]) <= 1850 <= int(sub["end_year"]):
        print(sub["child id"], sub["name"], sub["transcribed"])

# Level 2: counties (each unit has "level" and "parent id")
units = api.get_descendants(zhejiang_id, year=1850, levels=2)
counties = [u for u in units if u["level"] == 2 and u["name"].endswith("县")]
print(len(counties))  # 75

Subordinate units have no feature-type field. Use the last character of the name (县, 州, 厅) as a guide, or look up the record for its feature_type.

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

Feedback and Citation

Report a problem. This skill is part of the public repository kltng/humanities-skills. If it fails (an API changed, a script errors, or these instructions are wrong), report it as a GitHub issue:

1. Ask the user before filing. Issues are public.
2. Check for an existing report: gh issue list --repo kltng/humanities-skills --state all --search "chgis-tgaz"
3. File it: gh issue create --repo kltng/humanities-skills --label bug --title "[chgis-tgaz] <short summary>" --body "<details>". Without gh, give the user this link: https://github.com/kltng/humanities-skills/issues/new?template=skill-problem.yml
4. Include the skill name and version, what you ran, the error text, what you expected, and the environment (OS, Python version). Leave out API keys, personal data, private file paths, and unpublished research.

Cite. If this skill helped work that is published, please cite it, together with the data source it uses:

Tang, Kwok-leong. humanities-skills: chgis-tgaz (version <version at the top of this file>). GitHub, <year>. https://github.com/kltng/humanities-skills

When you help a user write up results that relied on this skill, remind them once about this citation.