Introduction

CHGIS XML API - is a simple read-only interface that searches the contents of the China Historical GIS placename database. A traditional form-based user interface that queries the same database can be accessed on the Search Tools page of the CHGIS website.

Currently the CHGIS database contains some 250,000 placename spellings, representing more than 175,000 locations on the ground, of which more than 50,000 are historical placenames. This interface serves as a free gazetteer for placenames in China, and will accept queries as strings of ascii letters (for romanized placenames) or strings of UTF-8 encoded Chinese Characters (as either Simplified or Complex glyphs).

The XML API was developed by Lex Berman as a component of the international collaborative project, Integrating Chinese Literary, Historical, and Geographical Databases, based at McGill University, Montreal.

Usage

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

  1. Placename Search
    method -> http://chgis.hmdc.harvard.edu/xml/placename/QUERY-STRING

  2. Unique Identifier Search
    method -> http://chgis.hmdc.harvard.edu/xml/id/UNIQUE-ID

  3. Combined Placename and Year Search
    method -> http://chgis.hmdc.harvard.edu/xml/query/PLACENAME/YEAR

Usage:

  1. PLACENAME - replace QUERY-STRING with the placename to be searched

  2. UNIQUE ID - replace UNIQUE-ID with the CHGIS ID to be searched. (The CHGIS ID can be Point ID, Polygon ID, Line ID, or System ID, as listed in the CHGIS data layers).

  3. PLACENAME and YEAR - replace PLACENAME with placename to be searched and YEAR with the year the placename was extant. (note, the forward slash / is mandatory between PLACENAME and YEAR, and BOTH values must be provided for the query to function.)

Blank spaces are accepted. Chinese Characters should be sent as plain UTF-8 encodings, not URLencoded hexadecimal strings. Note: for historical records the valid years of the database are -222 to 1911. These records are only available for a limited area, however. If you are interested in the widest spatial coverage, please search for data current in the year 1820, which contains a nationwide coverage (approximately 12,000 locations). If you are searching for villages, please search for data current in the year 1911, for which there are some 35,000 locations in the database. Limiting the search to the year 1990 will show only records from the CITAS dataset, while searching for the year 1994 will show only records from the GNS dataset.

Examples

The following examples are provided, please test them and view the source of the returned XML:

Placename Search Examples

Unique ID Search Examples

Combined Placename and Years Search Example

Web Service Schema [view schema]

The CHGIS web service can be validated with a RELAX NG schema. The XML returned by the web service is composed of two main sections, a HEADER section and a RESULTS section.

The HEADER section contains some basic information about the query itself, the number of total results found in the database, the number of results transmitted to the requestor, the execution time, etc.

The RESULTS section contains a series of < item > elements, each of which represent a unique record found in the database. The sub-elements of the < item > element, and their related attributes are currently documented in the CHGIS API RELAX NG schema. More extensive documentation and data dictionary will be posted here soon.

Access Rules

The CHGIS datasets and web service are freely available for academic and non-commercial use, according to the terms stated in the CHGIS End User License Agreement. However, to avoid the wholesale scraping of the web service, we have imposed a restriction of 200 results returned for any given query. We ask that users do not create automated processes to systematically scrape the entire contents of the CHGIS database. Wholesale copying and redistribution of the CHGIS database is a violation of the License Agreement. If you wish to establish a direct, unrestricted web service connection, please contact the CHGIS Project Manager who can assist you in arranging a formal data-sharing agreement. Authorized connections based on existed data-sharing agreements will have unrestricted access to the CHGIS web service.