zhongwei/gh-kltng-humanities-skills-chgis-tgaz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:35:14 +08:00
commit 747ef68ea4
5 changed files with 573 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "chgis-tgaz",
"description": "Query the CHGIS Temporal Gazetteer API for historical Chinese placenames and administrative units from 222 BCE to 1911 CE",
"version": "1.0.0",
"author": {
"name": "Kwok-leong Tang",
"notes": "Created with AI assistance from Claude and Z.ai"
},
"skills": [
"./"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# chgis-tgaz
Query the CHGIS Temporal Gazetteer API for historical Chinese placenames and administrative units from 222 BCE to 1911 CE

348
SKILL.md Normal file
View File

@@ -0,0 +1,348 @@
---
name: chgis-tgaz
description: Query the China Historical GIS (CHGIS) Temporal Gazetteer (TGAZ) API to search for historical Chinese placenames from 222 BCE to 1911 CE. Use this skill when searching for information about historical Chinese places, administrative units, or geographic locations during the dynastic period. Applicable for queries about historical place names, administrative hierarchies, or when users mention specific Chinese locations with historical context.
version: 1.0.0
license: MIT
creator: AI
author: Kwok-leong Tang
contributors:
- Claude (AI Assistant)
- Z.ai (AI Platform)
---
# CHGIS TGAZ
## Overview
The CHGIS Temporal Gazetteer (TGAZ) skill enables querying the China Historical GIS database to search for historical Chinese placenames and administrative units from 222 BCE to 1911 CE. The API accepts UTF-8 encoded Chinese characters and Romanized transcriptions, making it accessible for searches in multiple languages.
## When to Use This Skill
Apply this skill when users:
- Search for historical Chinese placenames or locations
- Ask about administrative units during China's dynastic period
- Need to verify historical place names or their spellings
- Request information about administrative hierarchies (provinces, prefectures, counties)
- Inquire about places that existed during specific historical years
- Need to identify modern equivalents of historical placenames
- Research geographic locations mentioned in historical texts
## Core Capabilities
### 1. Placename Search by Name
Search for places using Chinese characters or Romanized names.
**When to use:** User provides a place name and wants to find matching records.
**Basic approach:**
```python
import requests
# Basic search
url = "https://chgis.hudci.org/tgaz/placename"
params = {
"n": "beijing", # or "北京"
"fmt": "json"
}
response = requests.get(url, params=params)
data = response.json()
```
**Example user requests:**
- "Find information about Beijing in the CHGIS database"
- "Search for the place called 苏州 in Chinese history"
- "What records exist for Hangzhou?"
### 2. Historical Year-Specific Searches
Search for places as they existed in a specific historical year.
**When to use:** User specifies or implies a particular time period.
**Approach:**
```python
# Search with specific year
params = {
"n": "suzhou",
"yr": "1820", # Use negative for BCE: "-100"
"fmt": "json"
}
response = requests.get(url, params=params)
```
**Example user requests:**
- "What was the administrative status of Nanjing in 1750?"
- "Find counties in Zhejiang province in the year 1850"
- "Search for places named Chang'an during the Tang dynasty" (would need approximate year like 750)
**Important:** The valid year range is -222 to 1911 (222 BCE to 1911 CE).
### 3. Feature Type Filtering
Search for specific types of administrative units.
**When to use:** User asks about a specific administrative level or type.
**Approach:**
```python
# Search for a specific administrative type
params = {
"n": "suzhou",
"yr": "1820",
"ftyp": "fu", # Superior prefecture
"fmt": "json"
}
response = requests.get(url, params=params)
```
**Common feature types:**
- `xian` (县) - County
- `zhou` (州) - Prefecture
- `fu` (府) - Superior prefecture
- `sheng` (省) - Province
- `dao` (道) - Circuit
- `lu` (路) - Route
- `jun` (郡) - Commandery
**Example user requests:**
- "Find all counties (xian) named Anqing"
- "What prefectures existed in 1650?"
- "Search for superior prefectures (fu) in Jiangsu"
### 4. Hierarchical Searches
Search for places within a specific parent administrative unit.
**When to use:** User specifies a place within a broader geographic region.
**Approach:**
```python
# Search within a parent unit
params = {
"n": "ningbo",
"ipar": "zhejiang", # Immediate parent
"yr": "1850",
"fmt": "json"
}
response = requests.get(url, params=params)
```
**Example user requests:**
- "Find places named Xiaoshan in Zhejiang province"
- "What counties were in Yunnan in 1800?"
- "Search for administrative units under Jiangnan"
### 5. Retrieve Specific Records by ID
Fetch a complete record when the unique TGAZ ID is known.
**When to use:** User provides or you've discovered a specific TGAZ ID.
**Approach:**
```python
# Retrieve specific record
tgaz_id = "hvd_32180"
url = f"https://chgis.hudci.org/tgaz/placename/{tgaz_id}"
params = {"fmt": "json"}
response = requests.get(url, params=params)
```
**ID format:** TGAZ IDs use the prefix `hvd_` (e.g., CHGIS ID 32180 becomes TGAZ ID hvd_32180)
## Search Strategy Best Practices
### Start Broad, Then Narrow
Begin with simple queries and add parameters progressively:
1. **First attempt:** Basic placename only
```python
params = {"n": "guangzhou", "fmt": "json"}
```
2. **If too many results:** Add year
```python
params = {"n": "guangzhou", "yr": "1820", "fmt": "json"}
```
3. **If still ambiguous:** Add feature type or parent
```python
params = {"n": "guangzhou", "yr": "1820", "ftyp": "fu", "fmt": "json"}
```
### Handling Chinese Characters
**Always use UTF-8 encoding directly:**
- ✅ Correct: `"n": "北京"`
- ❌ Wrong: URL-encoding Chinese characters
**The API accepts both Chinese and Romanized names:**
- `"n": "beijing"` and `"n": "北京"` both work
- Try both if one doesn't return expected results
### Format Preferences
**Always request JSON format** for easier parsing:
```python
params = {"n": "place_name", "fmt": "json"}
```
Without `fmt=json`, the API returns XML by default.
## Interpreting Results
### Multiple Results
Faceted searches often return multiple records because:
- Places had the same name in different locations
- Administrative status changed over time
- Names were reused across different periods
**Approach:** Present all relevant results to the user or ask for clarification.
### Understanding Historical Context
Records include:
- **Begin/end dates** showing when the placename was valid
- **Administrative hierarchy** showing parent-child relationships
- **Multiple spellings** in different languages/transcriptions
- **Geographic coordinates** for mapping
### No Results
If a search returns no results, try:
1. Alternative spellings or transcriptions
2. Broader search (remove year or feature type constraints)
3. Search in Chinese characters if using Romanization (or vice versa)
4. Verify the year is within valid range (-222 to 1911)
## Common Patterns
### Pattern 1: Historical Research Query
User asks about a place in a historical context.
```python
# Example: "What was Yangzhou during the Qing dynasty?"
params = {
"n": "yangzhou",
"yr": "1750", # Mid-Qing approximate year
"fmt": "json"
}
```
### Pattern 2: Administrative Hierarchy Query
User wants to understand administrative structure.
```python
# Example: "What were the counties in Jiangsu in 1850?"
# First get Jiangsu, then search with it as parent
params = {
"n": "jiangsu",
"yr": "1850",
"ftyp": "sheng",
"fmt": "json"
}
# Then search for counties
params = {
"ipar": "jiangsu",
"yr": "1850",
"ftyp": "xian",
"fmt": "json"
}
```
### Pattern 3: Verification Query
User wants to verify a place name or identification.
```python
# Example: "Is this the correct ID for Beijing?"
tgaz_id = "hvd_12345"
url = f"https://chgis.hudci.org/tgaz/placename/{tgaz_id}"
params = {"fmt": "json"}
```
## Resources
### API Reference Documentation
Detailed API specifications, query parameters, and examples are available in:
- `references/api_reference.md` - Complete API documentation
**When to read the reference:**
- When encountering unfamiliar query patterns
- For complete list of feature types
- When needing detailed parameter specifications
- For troubleshooting response formats
## Example Code Template
```python
import requests
def search_tgaz(placename, year=None, feature_type=None, parent=None):
"""
Search CHGIS TGAZ for historical placenames.
Args:
placename: Name of place (Chinese or Romanized)
year: Historical year (-222 to 1911)
feature_type: Admin type (xian, fu, zhou, etc.)
parent: Parent administrative unit
Returns:
JSON response from API
"""
url = "https://chgis.hudci.org/tgaz/placename"
params = {"n": placename, "fmt": "json"}
if year:
params["yr"] = str(year)
if feature_type:
params["ftyp"] = feature_type
if parent:
params["ipar"] = parent
response = requests.get(url, params=params)
response.raise_for_status()
return response.json()
def get_placename_by_id(tgaz_id):
"""
Retrieve specific placename record by TGAZ ID.
Args:
tgaz_id: TGAZ unique identifier (format: hvd_XXXXX)
Returns:
JSON response from API
"""
url = f"https://chgis.hudci.org/tgaz/placename/{tgaz_id}"
params = {"fmt": "json"}
response = requests.get(url, params=params)
response.raise_for_status()
return response.json()
# Example usage
results = search_tgaz("beijing", year=1800)
specific_record = get_placename_by_id("hvd_32180")
```
## Tips for Effective Use
1. **Default to JSON format** - Always include `"fmt": "json"` for easier parsing
2. **Start simple** - Begin with just the placename, add filters if needed
3. **Consider time period** - Historical names changed; try different years
4. **Try both scripts** - Search in both Chinese characters and Romanization
5. **Check valid years** - Ensure years are within -222 to 1911
6. **Present options** - When multiple results exist, show them to the user
7. **Explain context** - Help users understand why multiple records exist
8. **Handle errors gracefully** - No results doesn't mean wrong query; try variations

49
plugin.lock.json Normal file
View File

@@ -0,0 +1,49 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:kltng/humanities-skills:chgis-tgaz",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "a487aa4ce257e709f3933fa6788f99265c5fc3dc",
"treeHash": "89d3d0da3a1df60d16cd2aa9da9850e07af2427cdefdc34e742fad9a4f6dba97",
"generatedAt": "2025-11-28T10:19:53.935413Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "chgis-tgaz",
"description": "Query the CHGIS Temporal Gazetteer API for historical Chinese placenames and administrative units from 222 BCE to 1911 CE",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "4f996d038ab7c1d6042176353773899f59cf213dad0f3ad91a5b8b61825bc209"
},
{
"path": "SKILL.md",
"sha256": "75c69d36bc27a10fc3e4a64cb1547ef51a80d66f509661c000f5c71260da6b44"
},
{
"path": "references/api_reference.md",
"sha256": "742c59f011ee6f0b2f7640b18e49da8a922eb1c215f72024f3faf484c2953559"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "b8e0db9978cfa32af59d4e89e109bc9d2047c18cae7541e2e44b73747a0516f5"
}
],
"dirSha256": "89d3d0da3a1df60d16cd2aa9da9850e07af2427cdefdc34e742fad9a4f6dba97"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

161
references/api_reference.md Normal file
View File

@@ -0,0 +1,161 @@
# CHGIS TGAZ API Reference
The China Historical GIS (CHGIS) Temporal Gazetteer (TGAZ) is a RESTful API providing access to historical Chinese placenames from 222 BCE to 1911 CE. The API supports searches in UTF-8 encoded Chinese characters and Romanized transcriptions.
## Base URL
```
https://chgis.hudci.org/tgaz
```
## Historical Coverage
Valid years: **-222 to 1911** (222 BCE to 1911 CE)
## API Methods
### 1. Canonical Placename Search
Retrieve a specific placename record by its unique ID.
**Endpoint Pattern:**
```
GET /placename/{UNIQUE_ID}
```
**ID Format:**
- TGAZ uses IDs with the prefix `hvd_`
- CHGIS IDs are converted by adding this prefix
- Example: CHGIS ID `32180` → TGAZ ID `hvd_32180`
**Example Request:**
```
GET https://chgis.hudci.org/tgaz/placename/hvd_32180
```
**Default Response Format:** XML (can be changed with `fmt` parameter)
---
### 2. Faceted Search
Search using multiple query parameters to find placenames matching specific criteria.
**Endpoint:**
```
GET /placename
```
**Query Parameters:**
| Parameter | Code | Description | Example |
|-----------|------|-------------|---------|
| Placename | `n` | Name of the place (Chinese characters or Romanization) | `n=mengla` or `n=蒙拉` |
| Year | `yr` | Historical year (use `-` prefix for BCE) | `yr=1820` or `yr=-100` |
| Feature Type | `ftyp` | Administrative type (xian, zhou, fu, etc.) | `ftyp=xian` |
| Data Source | `src` | Source dataset identifier | `src=chgis` |
| Immediate Parent | `ipar` | Name of parent administrative unit | `ipar=yunnan` |
| Format | `fmt` | Output format (`xml` or `json`) | `fmt=json` |
**Important Notes:**
- **Blank spaces are accepted** in placename, feature type, and immediate parent values (no need to URL-encode spaces)
- **Chinese characters** should be sent as plain UTF-8 encodings, NOT URLencoded hexadecimal strings
- Default output is XML unless `fmt=json` is specified
- Multiple parameters can be combined in a single query
**Example Requests:**
Basic search by placename:
```
GET https://chgis.hudci.org/tgaz/placename?n=mengla
```
Search with year and feature type:
```
GET https://chgis.hudci.org/tgaz/placename?n=mengla&yr=1820&ftyp=xian
```
Search in JSON format:
```
GET https://chgis.hudci.org/tgaz/placename?n=北京&yr=1800&fmt=json
```
Complex search with parent:
```
GET https://chgis.hudci.org/tgaz/placename?n=hangzhou&yr=1500&ipar=zhejiang&fmt=json
```
---
## Common Feature Types
Historical Chinese administrative units include:
- `xian` (县) - County
- `zhou` (州) - Prefecture
- `fu` (府) - Superior prefecture
- `sheng` (省) - Province
- `dao` (道) - Circuit
- `lu` (路) - Route
- `jun` (郡) - Commandery
---
## Response Structure
### XML Response (Default)
The API returns XML with placename records including:
- Unique identifiers
- Placename spellings (multiple transcriptions/languages)
- Historical dates (begin/end validity)
- Administrative hierarchy
- Geographic coordinates
- Feature type classifications
### JSON Response
Use `fmt=json` parameter to receive responses in JSON format with the same data structure.
---
## Data Sources
The TGAZ integrates multiple historical gazetteer databases:
- **CHGIS** - China Historical GIS
- **Toponimika** - Historical Gazetteer of Russia
- **Greater Tibet** - Gazetteer of Historical Monasteries
---
## Usage Notes
1. **Character Encoding**: Always use UTF-8 for Chinese characters
2. **Year Format**: Use negative numbers for BCE dates (e.g., `-100` for 100 BCE)
3. **Search Strategy**: Start with broad searches (just placename) and add parameters to narrow results
4. **Multiple Results**: Faceted searches may return multiple matching records
5. **Historical Context**: Consider that placenames, boundaries, and administrative statuses changed over time
---
## Example Use Cases
### Find a county in a specific year
```
GET https://chgis.hudci.org/tgaz/placename?n=suzhou&yr=1820&ftyp=xian&fmt=json
```
### Search using Chinese characters
```
GET https://chgis.hudci.org/tgaz/placename?n=苏州府&yr=1750&fmt=json
```
### Search within a province
```
GET https://chgis.hudci.org/tgaz/placename?n=ningbo&ipar=zhejiang&yr=1850&fmt=json
```
### Retrieve specific record by ID
```
GET https://chgis.hudci.org/tgaz/placename/hvd_32180
```