THL Toolbox > Developers' Zone > Ruby On Rails Development > Using RoR Place Dictionary Web Services

Using RoR Place Dictionary Web Services API

Contributor(s): Tom Benner, Than Grove, Andres Montano

The Place Dictionary's API provides two methods of querying data, an FID search and a name search. The format of the responses can be either HTML (in the THL layout), XML, or JSON, and is specified by using, respectively, no file extension, .xml, or .json. We'll use .json for these examples.

Fetching Root Items

All root items can be retrieved through:

http://places.thlib.org/features.json

http://places.thlib.org/features.xml

Features By FID

A single feature of FID 200 can be found at (cached):

http://places.thlib.org/features/200.json

http://places.thlib.org/features/200.xml

Or (not cached):

http://places.thlib.org/features/by_fid/200.json

http://places.thlib.org/features/by_fid/200.xml

"by_fid" is designed for getting multiple features delimited by any non-decimal character:

http://places.thlib.org/features/by_fid/200,34.json

http://places.thlib.org/features/by_fid/200,34.xml

Or:

http://places.thlib.org/features/by_fid/F200,F34.json

http://places.thlib.org/features/by_fid/F200,F34.xml

Note that the response for the "by" URLs is always a set of features, wrapped in a "features" property, even with a single FID query.

Features By Name

This has become used for the general-use queries. A simply query for features whose names contain a certain string can be made like this:

http://places.thlib.org/features/by_name/china.json

http://places.thlib.org/features/by_name/china.xml

The following parameters are also, supported, though, as is an empty query string ("by_name/.json") to return all features that match the other parameters:

• page: page number of results
• per_page: the count of results per page
• feature_type: the id of an object_type that the features are categorized as (this can also be a comma-delimited list, which will return features that match any of the listed types)
• scope: the scope in which the query string will be searched for; by default only names are searched ("name"), but "full_text" can be used to do a full text search (names and descriptions)
• view_code: the view code that the features' information should be returned in (e.g. "roman.popular")

Fetching Relationships

Parent relations and ancestor information is available on the API for fetching information for a single item:

http://places.thlib.org/features/431.xml

http://places.thlib.org/features/431.json

The children of an item are listed at:

http://places.thlib.org/features/431/children.json

http://places.thlib.org/features/431/children.xml

A treed listing of the items's descendants is available at the following URL:

http://places.thlib.org/features/431/all.json

http://places.thlib.org/features/431/all.xml

or for all items:

http://places.thlib.org/features/all.json

http://places.thlib.org/features/all.xml

and

http://places.thlib.org/features/431/nested.json

http://places.thlib.org/features/431/nested.xml

or for all items:

http://places.thlib.org/features/nested.json

http://places.thlib.org/features/nested.xml

To fetch all descendantes of a specific category in a flat list:

http://places.thlib.org/features/431/list.xml

http://places.thlib.org/features/431/list.json

or for all items:

http://places.thlib.org/features/list.xml

http://places.thlib.org/features/list.json

Features by Topic

To find the data for a group of features determined by area and type, the following URL structure should be used:

http://places.thlib.org/features/431/by_topic/555.xml

http://places.thlib.org/features/431/by_topic/555.json

http://places.thlib.org/features/431/by_topic/555.txt

http://places.thlib.org/features/431/by_topic/555.csv

The first number represents the feature id of the area to which the search would be limited. In this case, 431 represents Qinghai province. The second number stands for the topic or type of feature by which the results should be filtered. This is a id of the appropriate knowledge map. In this case 555 represents "Buddhist & Bön Religious Settlements". So, the above URLs would return the data for all religious settlements in Qinghai, in either an xml, json, or txt format. It is also possible to specify several fids and topic ids (separated by a non-numeric character such as comma or dash). The xml, json, and txt API will include all descendants irrespective of perspective of the specified feature ids and the names will be given in the "roman.popular" view. The txt and csv API does support restricting the descendants by a specific perspective using the perspective_code. The txt API can also displaying the names with specific views using the view_code such as:

http://places.thlib.org/features/431/by_topic/106.txt?perspective_code=pol.admin.hier&view_code=pri.tib.sec.chi

http://places.thlib.org/features/2/by_topic/20.csv?perspective_code=pol.admin.hier

To get a list of all feature-subject associations:

http://places.thlib.org/characteristics_list.json

Feature by Geocode

To find a feature by its geocode the following URL structure should be used:

http://places.thlib.org/features/by_geo_code/A-48.xml?geo_code_type=bell.id

http://places.thlib.org/features/by_geo_code/A-48.json?geo_code_type=bell.id

geo_code_type specifies the GeoCodeType code.

Item by Legacy ID

To find an item by its legacy id (old id used from a previous system) the following URL structure should be used:

http://subjects.kmaps.virginia.edu/features/by_old_pid/F1.xml

http://subjects.kmaps.virginia.edu/features/by_old_pid/F1.json

Descriptions

To get the descriptions for a feature the following URL structure should be used:

http://localhost/places/features/637/descriptions.xml

http://localhost/places/features/637/descriptions.json

To get a specific description the following URL structure should be used:

http://localhost/places/features/637/descriptions/16.json

http://localhost/places/features/637/descriptions/16.xml

Note: Because the complexity of the searches and the amount of data returned, these URLs will take some time, often minutes, to resolve. They therefore cannot be used on the fly but merely for obtaining data for processing .

JSONP

All json API requests (except by topic calls) support a callback parameter where you can set a function name to wrap a JSONP response. For instance:

http://places.thlib.org/features/by_fid/200.json?callback=f

http://places.thlib.org/features/200.json?callback=f

http://places.thlib.org/features/by_name/china.json?callback=f

http://places.thlib.org/features/by_geo_code/A-48.json?geo_code_type=bell.id&callback=f

http://localhost/places/features/637/descriptions.json?callback=f

http://localhost/places/features/637/descriptions/16.json?callback=f

Note about Unicode

An important note, especially if the query string contains non-Roman characters, is that the query string should be encoded as UTF-8.

To encode a string to UTF-8 in JavaScript, the following function can be used:

function utf8_encode(string){
	string = string.replace(/rn/g,"n");
	var utftext = "";
	for (var n = 0; n < string.length; n++) {
		var c = string.charCodeAt(n);
		if (c < 128) {
			utftext += String.fromCharCode(c);
		}else if((c > 127) && (c < 2048)) {
			utftext += String.fromCharCode((c >> 6) | 192);
			utftext += String.fromCharCode((c & 63) | 128);
		}else {
			utftext += String.fromCharCode((c >> 12) | 224);
			utftext += String.fromCharCode(((c >> 6) & 63) | 128);
			utftext += String.fromCharCode((c & 63) | 128);
		}
	}
	return utftext;
}

GIS Resources

GeoServer is the service we use for delivering GIS data, but the parameters it requires are often complex relative to what many people may need to specify. To mitigate this, we have built in a GIS resource service into the Place Dictionary. This delivers three types of files: GML, KML, and shapefiles, depending on whether the URL's file extension is, respectively, .gml, .kml, or .shp. As with the "Features By FID" service above, either a single FID, or multiple FIDs can be specified, using any non-integer and non-decimal character as the delimiter, like:

http://places.thlib.org/features/gis_resources/5276.gml

Or:

http://places.thlib.org/features/gis_resources/5276,5277.gml

Data that includes both the feature and all of its contained features can also be requested, by adding "?contained=1" to the end of the URL, like:

http://places.thlib.org/features/gis_resources/5276.gml?contained=1

Creating JSON Data File for DataTables

There are datatable lists for such things as TAR Monasteries: http://www.thlib.org/places/monasteries/list/tar/, that use a JSON data file exported through the Place Dictionary API and massaged into the necessary JSON format (for overview and help, see help with place dictionary interactive data tables). The JSON file for the above list is found in http://www.thlib.org/places/monasteries/js/tar-monasteries.js (though properly it is a .json file). It is created through the following process:

1. Export an XML file containing the date for all monasteries in TAR by going to: http://dev-place.thlib.org/features/2/by_topic/555.xml This finds all features for TAR (2) that are categorized by the KMap topic of monasteries (555). One goes to that URL in a browser and saves the result. Or else open that URL through Oxygen and save the results locally, as something like tar-monasteries-555.xml.
2. Download the two XSLT stylesheets (right click and save as):
   1. AddCountyAndProvince.xsl
   2. dataXML2JSON.xsl
3. Open the data file download from the place dictionary (tar-monasteries-555.xml) in Oxygen
4. Using Oxygen create a transformation that transforms the ${currentFileURL} with the XSLT AddCountyAndProvince.xsl and click on the "Additional XSLT stylesheets" button and add dataXML2JSON.xsl as a second stylesheet.
5. Apply that transformation scenario to the XML file and save the results as tar-monasteries.js
6. Place the "tar-monasteries.js" in the /places/monasteries/js/ folder.

Note: At the top of the JSON file there are two fields recording the number of monasteries in the list:

"sEcho": 3,
    "iTotalRecords": 567,
    "iTotalDisplayRecords": 567,
    "aaData": [
....

Both fields "iTotalRecords" and "iTotalDisplayRecords" need to reflect the exact number of monasteries listed. So, if the list is edited by hand and monasteries are added or removed, these fields must be adjusted accordingly. One can use Oxygen to count the number of monasteries by searching on "]," and clicking "Find All", add one to the resulting number found for the total number of monasteries. (The last monastery entry does not have a comma after it.)

Provided for unrestricted use by the Tibetan and Himalayan Library