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.
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:
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.
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
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.
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.