# 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
```