Using Ror Knowledge Maps Web Services

THL Toolbox > Developers' Zone > Ruby On Rails Development > Using RoR Knowledge Maps Web Services

Using RoR Knowledge Maps Web Services

Contributor(s): Andres Montano

The Kmaps Common Engine's API provides two methods of querying data, an Kmap ID search and a name search. The format of the responses can be either HTML, 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:

external link: http://subjects.kmaps.virginia.edu/features.json

external link: http://subjects.kmaps.virginia.edu/features.xml

Fetching Items By Kmap ID

A single item with Kmap ID 20 can be found at (cached):

external link: http://subjects.kmaps.virginia.edu/features/20.json

external link: http://subjects.kmaps.virginia.edu/features/20.xml

Or (not cached):

external link: http://subjects.kmaps.virginia.edu/features/by_fid/20.json

external link: http://subjects.kmaps.virginia.edu/features/by_fid/20.xml

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

external link: http://subjects.kmaps.virginia.edu/features/by_fid/20,5812.json

external link: http://subjects.kmaps.virginia.edu/features/by_fid/20,5812.xml

Or:

external link: http://subjects.kmaps.virginia.edu/features/by_fid/F20,F5812.json

external link: http://subjects.kmaps.virginia.edu/features/by_fid/F20,F5812.xml

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

Items By Name

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

external link: http://subjects.kmaps.virginia.edu/features/by_name/ritual.json

external link: http://subjects.kmaps.virginia.edu/features/by_name/ritual.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
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:

external link: http://subjects.kmaps.virginia.edu/features/20.xml

external link: http://subjects.kmaps.virginia.edu/features/20.json

The children of an item are listed at:

external link: http://subjects.kmaps.virginia.edu/features/20/children.json

external link: http://subjects.kmaps.virginia.edu/features/20/children.xml

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

external link: http://subjects.kmaps.virginia.edu/features/20/all.json

external link: http://subjects.kmaps.virginia.edu/features/20/all.xml

or for all items:

external link: http://subjects.kmaps.virginia.edu/features/all.json

external link: http://subjects.kmaps.virginia.edu/features/all.xml

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

external link: http://subjects.kmaps.virginia.edu/features/20/all_with_places.json

external link: http://subjects.kmaps.virginia.edu/features/20/all_with_places.xml

Also to fetch all items in a slightly different structure:

external link: http://subjects.kmaps.virginia.edu/features/20/nested.json

external link: http://subjects.kmaps.virginia.edu/features/20/nested.xml

or for all items:

external link: http://subjects.kmaps.virginia.edu/features/nested.json

external link: http://subjects.kmaps.virginia.edu/features/nested.xml

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

external link: http://subjects.kmaps.virginia.edu/features/20/list.xml

external link: http://subjects.kmaps.virginia.edu/features/20/list.json

or for all items:

external link: http://subjects.kmaps.virginia.edu/features/list.xml

external link: http://subjects.kmaps.virginia.edu/features/list.json

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

external link: http://subjects.kmaps.virginia.edu/features/20/list_with_places.xml

external link: http://subjects.kmaps.virginia.edu/features/20/list_with_places.json

Item by Code

To find an item by its code the following URL structure should be used:

external link: http://subjects.kmaps.virginia.edu/features/by_geo_code/A-48.xml?geo_code_type=bell.id

external link: http://subjects.kmaps.virginia.edu/features/by_geo_code/A-48.json?geo_code_type=bell.id

geo_code_type specifies the code type 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:

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

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

Descriptions

To get the descriptions for an item the following URL structure should be used:

external link: http://subjects.kmaps.virginia.edu/features/20/descriptions.xml

external link: http://subjects.kmaps.virginia.edu/features/20/descriptions.json

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

external link: http://subjects.kmaps.virginia.edu/features/20/descriptions/1.json

external link: http://subjects.kmaps.virginia.edu/features/20/descriptions/1.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 "by" json API requests support a callback parameter where you can set a function name to wrap a JSONP response. For instance:

external link: http://subjects.kmaps.virginia.edu/features/by_fid/20.json?callback=f

external link: http://subjects.kmaps.virginia.edu/features/20.json?callback=f

external link: http://subjects.kmaps.virginia.edu/features/by_name/ritual.json?callback=f

external link: http://subjects.kmaps.virginia.edu/features/by_geo_code/A-48.json?geo_code_type=bell.id&callback=f

external link: http://subjects.kmaps.virginia.edu/features/20/descriptions.json?callback=f

external link: http://subjects.kmaps.virginia.edu/features/20/descriptions/1.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;
}