Introduction

TGAZ API - is a read-only interface designed to search the contents of the China Historical GIS placename database. The TGAZ system architecture -- based loosely on the CHGIS XML API (2006) -- has been normalized and made more generic in order to integrate multiple data sources, and to allow for vernacular spellings or transcription methods in many languages.

This interface accepts queries for placenames in UTF-8 encoded strings or glyphs (for example, Chinese Simplified or Complex characters). Each placename recorded in the database is referred to as a spelling. A brief look at the project in diagrams (PDF). Demonstration

see also: CHGIS Temporal Gazetteer

Usage

Try this simple query form, or continue reading below for the API Usage Instructions:

The TGAZ web service is designed to receive RESTful URIs containing query values, and to return the results in XML format by default. The interface is READ-ONLY and currently provides two functions:

1. Canonical Placename Search
   method -> http://tgaz.fudan.edu.cn/tgaz/placename/UNIQUE_ID
2. Faceted Search
   method -> http://tgaz.fudan.edu.cn/tgaz/placename?QUERY_PARAMETER=VALUE

Instructions:

1. Canonical Placename Records - replace UNIQUE_ID with the unique placename ID to be searched. (The IDs being used are being minted for the TGAZ database with the prefix hvd_. For example, the IDs listed in the CHGIS data layers would have the prefix added, such as CHGIS ID 32180 = TGAZ ID hvd_32180).
2. Faceted Search - allows for a combinated of query parameters to be searched. A PLACENAME, YEAR, FEATURE TYPE, DATA SOURCE, and IMMEDIATE PARENT can be sent in the form of a query string, such as: ?n=mengla&yr=1820&ftyp=xian. Note: the default output is HTML, which can be reset using a FORMAT parameter, such as fmt=json

Blank spaces are accepted in the PLACENAME, FEATURE TYPE, IMMEDIATE PARENT values. Chinese Characters should be sent as plain UTF-8 encodings, not URLencoded hexadecimal strings. Note: for Chinese historical records the valid years of the database are -222 to 1911.

Canonical Placename

• http://tgaz.fudan.edu.cn/tgaz/placename/hvd_32180

Canonical Placename Formats

• json http://tgaz.fudan.edu.cn/tgaz/placename/json/hvd_80547
• rdf http://tgaz.fudan.edu.cn/tgaz/placename/rdf/hvd_135744
• html http://tgaz.fudan.edu.cn/tgaz/placename/html/hvd_9732
• xml http://tgaz.fudan.edu.cn/tgaz/placename/xml/hvd_96066

Faceted Search

parameters allowed:

• n: name (the spelling of the placename)
• yr: year of existence (the year during which the placename existed)
• ftyp: feature type (the the feature type, or class of placename)
• src: source (the data source, such as CHGIS, RAS)
• p: part of (the immediate parent jurisdiction where the place was located)
• fmt: format (the output format returned: xml, json, html)

Placename Examples

• Pinyin: http://tgaz.fudan.edu.cn/tgaz/placename?n=Tianbian
• Chinese: http://tgaz.fudan.edu.cn/tgaz/placename?n=晋阳
• Tibetan: http://tgaz.fudan.edu.cn/tgaz/placename?n=ར་ལོ་དགོན
• Russian: http://tgaz.fudan.edu.cn/tgaz/placename?n=Вятское Наместничество

Placename & Format Examples

• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=json&n=滚弄
• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=Rui'an Xian
• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=xml&n=温州

Placename & Year Examples

• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=龍&yr=800
• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=雙&yr=300

Placename & Feature Type Examples

• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=meng&ftyp=州
• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=鮑&ftyp=cun zhen

Placename & Part-of Parent Unit Examples

• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=茹&p=上谷郡
• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=盧溪&p=黔中

Multi-Parameter Faceted Search Examples

• http://tgaz.fudan.edu.cn/tgaz/placename?fmt=html&n=庆&ftyp=xian&yr=1420&P=Chuzhou