Using Ror Place Dictionary Web Services
<h3 class="heading-h6"><a name="THLToolboxhomegtDevelopersZonegtRubyOnRailsDevelopmentgtUsingRoRPlaceDictionaryWebServices" class="anchorpoint"></a><a href="/tools/wiki/home.html">THL Toolbox</a> > <a href="/tools/wiki/Developers%27%20Zone.html">Developers' Zone</a> > <a href="/tools/wiki/Ruby%20On%20Rails%20Development.html">Ruby On Rails Development</a> > Using RoR Place Dictionary Web Services</h3><p class="paragraph">
</p><h3 class="heading-h1"><a name="UsingRoRPlaceDictionaryWebServicesAPI" class="anchorpoint"></a>Using RoR Place Dictionary Web Services API</h3><p class="paragraph"><strong class="bold">Contributor(s)</strong>: Tom Benner, Than Grove, Andres Montano</p><p class="paragraph">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.
</p><h3 class="heading-h3"><a name="FeaturesByFID" class="anchorpoint"></a>Features By FID</h3><p class="paragraph">A single feature of FID 200 can be found at:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/200.json" target="rwikiexternal">http://places.thlib.org/features/by_fid/200.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/200.xml" target="rwikiexternal">http://places.thlib.org/features/by_fid/200.xml</a></span></p><p class="paragraph">Or</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/200.json" target="rwikiexternal">http://places.thlib.org/features/200.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/200.xml" target="rwikiexternal">http://places.thlib.org/features/200.xml</a></span></p><p class="paragraph">Multiple features can be delimited by any non-decimal character:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/200,34.json" target="rwikiexternal">http://places.thlib.org/features/by_fid/200,34.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/200,34.xml" target="rwikiexternal">http://places.thlib.org/features/by_fid/200,34.xml</a></span></p><p class="paragraph">Or:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/F200,F34.json" target="rwikiexternal">http://places.thlib.org/features/by_fid/F200,F34.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/F200,F34.xml" target="rwikiexternal">http://places.thlib.org/features/by_fid/F200,F34.xml</a></span></p><p class="paragraph">Note that the response is always a set of features, wrapped in a "features" property, even with a single FID query.
</p><h3 class="heading-h3"><a name="FeaturesByName" class="anchorpoint"></a>Features By Name</h3><p class="paragraph">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:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_name/china.json" target="rwikiexternal">http://places.thlib.org/features/by_name/china.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_name/china.xml" target="rwikiexternal">http://places.thlib.org/features/by_name/china.xml</a></span></p><p class="paragraph">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:
</p><ul class="star"><li>page: page number of results</li>
<li>per_page: the count of results per page</li>
<li>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)</li>
<li>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)</li>
<li>view_code: the view code that the features' information should be returned in (e.g. "roman.popular")</li></ul><p class="paragraph">
</p><h3 class="heading-h3"><a name="FeaturesbyTopic" class="anchorpoint"></a>Features by Topic</h3><p class="paragraph">To find the data for a group of features determined by area and type, the following URL structure should be used:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/431/by_topic/555.xml" target="rwikiexternal">http://places.thlib.org/features/431/by_topic/555.xml</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/431/by_topic/555.json" target="rwikiexternal">http://places.thlib.org/features/431/by_topic/555.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/431/by_topic/555.txt" target="rwikiexternal">http://places.thlib.org/features/431/by_topic/555.txt</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/431/by_topic/555.csv" target="rwikiexternal">http://places.thlib.org/features/431/by_topic/555.csv</a></span></p><p class="paragraph">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:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/431/by_topic/106.txt?perspective_code=pol.admin.hier&view_code=pri.tib.sec.chi" target="rwikiexternal">http://places.thlib.org/features/431/by_topic/106.txt?perspective_code=pol.admin.hier&view_code=pri.tib.sec.chi</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/2/by_topic/20.csv?perspective_code=pol.admin.hier" target="rwikiexternal">http://places.thlib.org/features/2/by_topic/20.csv?perspective_code=pol.admin.hier</a></span>
</p><h3 class="heading-h3"><a name="FeaturebyGeocode" class="anchorpoint"></a>Feature by Geocode</h3><p class="paragraph">To find a feature by its geocode the following URL structure should be used:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_geo_code/A-48.xml?geo_code_type=bell.id" target="rwikiexternal">http://places.thlib.org/features/by_geo_code/A-48.xml?geo_code_type=bell.id</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_geo_code/A-48.json?geo_code_type=bell.id" target="rwikiexternal">http://places.thlib.org/features/by_geo_code/A-48.json?geo_code_type=bell.id</a></span></p><p class="paragraph">geo_code_type specifies the GeoCodeType code.
</p><h3 class="heading-h3"><a name="Descriptions" class="anchorpoint"></a>Descriptions</h3><p class="paragraph">To get the descriptions for a feature the following URL structure should be used:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost/places/features/637/descriptions.xml" target="rwikiexternal">http://localhost/places/features/637/descriptions.xml</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost/places/features/637/descriptions.json" target="rwikiexternal">http://localhost/places/features/637/descriptions.json</a></span></p><p class="paragraph">To get a specific description the following URL structure should be used:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost/places/features/637/descriptions/16.json" target="rwikiexternal">http://localhost/places/features/637/descriptions/16.json</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost/places/features/637/descriptions/16.xml" target="rwikiexternal">http://localhost/places/features/637/descriptions/16.xml</a></span></p><p class="paragraph">
<strong class="bold">Note</strong>: <em class="italic">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 </em>.
</p><h3 class="heading-h3"><a name="JSONP" class="anchorpoint"></a>JSONP</h3><p class="paragraph">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:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_fid/200.json?callback=f" target="rwikiexternal">http://places.thlib.org/features/by_fid/200.json?callback=f</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/200.json?callback=f" target="rwikiexternal">http://places.thlib.org/features/200.json?callback=f</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_name/china.json?callback=f" target="rwikiexternal">http://places.thlib.org/features/by_name/china.json?callback=f</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/by_geo_code/A-48.json?geo_code_type=bell.id&callback=f" target="rwikiexternal">http://places.thlib.org/features/by_geo_code/A-48.json?geo_code_type=bell.id&callback=f</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost/places/features/637/descriptions.json?callback=f" target="rwikiexternal">http://localhost/places/features/637/descriptions.json?callback=f</a></span></p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://localhost/places/features/637/descriptions/16.json?callback=f" target="rwikiexternal">http://localhost/places/features/637/descriptions/16.json?callback=f</a></span>
</p><h3 class="heading-h3"><a name="NoteaboutUnicode" class="anchorpoint"></a>Note about Unicode</h3><p class="paragraph">An important note, especially if the query string contains non-Roman characters, is that the query string should be encoded as UTF-8.</p><p class="paragraph">To encode a string to UTF-8 in JavaScript, the following function can be used:</p><div class="code"><pre>function utf8_encode(string){
string = string.replace(/rn/g,<span class="java-quote">"n"</span>);
<span class="java-keyword">var</span> utftext = <span class="java-quote">""</span>;
<span class="java-keyword">for</span> (<span class="java-keyword">var</span> n = 0; n < string.length; n++) {
<span class="java-keyword">var</span> c = string.charCodeAt(n);
<span class="java-keyword">if</span> (c < 128) {
utftext += <span class="java-object">String</span>.fromCharCode(c);
}<span class="java-keyword">else</span> <span class="java-keyword">if</span>((c > 127) && (c < 2048)) {
utftext += <span class="java-object">String</span>.fromCharCode((c >> 6) | 192);
utftext += <span class="java-object">String</span>.fromCharCode((c & 63) | 128);
}<span class="java-keyword">else</span> {
utftext += <span class="java-object">String</span>.fromCharCode((c >> 12) | 224);
utftext += <span class="java-object">String</span>.fromCharCode(((c >> 6) & 63) | 128);
utftext += <span class="java-object">String</span>.fromCharCode((c & 63) | 128);
}
}
<span class="java-keyword">return</span> utftext;
}</pre></div><p class="paragraph">
</p><h3 class="heading-h3"><a name="GISResources" class="anchorpoint"></a>GIS Resources</h3><p class="paragraph">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:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/gis_resources/5276.gml" target="rwikiexternal">http://places.thlib.org/features/gis_resources/5276.gml</a></span></p><p class="paragraph">Or:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/gis_resources/5276,5277.gml" target="rwikiexternal">http://places.thlib.org/features/gis_resources/5276,5277.gml</a></span></p><p class="paragraph">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:</p><p class="paragraph"><img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://places.thlib.org/features/gis_resources/5276.gml?contained=1" target="rwikiexternal">http://places.thlib.org/features/gis_resources/5276.gml?contained=1</a></span></p><p class="paragraph"><a name="jsondtfiles" class="anchorpoint"></a>
</p><h3 class="heading-h3"><a name="CreatingJSONDataFileforDataTables" class="anchorpoint"></a>Creating JSON Data File for DataTables</h3><p class="paragraph">There are datatable lists for such things as TAR Monasteries: <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/places/monasteries/list/tar/," target="rwikiexternal">http://www.thlib.org/places/monasteries/list/tar/,</a></span> that use a JSON data file exported through the Place Dictionary API and massaged into the necessary JSON format (for overview and help, see <a href="/tools/wiki/help%20with%20place%20dictionary%20interactive%20data%20tables.html">help with place dictionary interactive data tables</a>). The JSON file for the above list is found in <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://www.thlib.org/places/monasteries/js/tar-monasteries.js" target="rwikiexternal">http://www.thlib.org/places/monasteries/js/tar-monasteries.js</a></span> (though properly it is a .json file). It is created through the following process:</p><ol><li>Export an XML file containing the date for all monasteries in TAR by going to: <img src="/" alt="external link: " title="external link"/><span class="nobr"><a href="http://dev-place.thlib.org/features/2/by_topic/555.xml" target="rwikiexternal">http://dev-place.thlib.org/features/2/by_topic/555.xml</a></span> 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.</li>
<li>Download the two XSLT stylesheets (right click and save as):<ol><li><span class="nobr"><img src="/" alt="external link: " title="external link"/><a href="https://collab.itc.virginia.edu/access/content/group/c06fa8cf-c49c-4ebc-007f-482de5382105/Web%20Development/xslt/AddCountyAndProvince.xsl" target="rwikiexternal">AddCountyAndProvince.xsl</a></span></li>
<li><span class="nobr"><img src="/" alt="external link: " title="external link"/><a href="https://collab.itc.virginia.edu/access/content/group/c06fa8cf-c49c-4ebc-007f-482de5382105/Web%20Development/xslt/dataXML2JSON.xsl" target="rwikiexternal">dataXML2JSON.xsl</a></span></li></ol>
</li>
<li>Open the data file download from the place dictionary (tar-monasteries-555.xml) in Oxygen</li>
<li>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.</li>
<li>Apply that transformation scenario to the XML file and save the results as tar-monasteries.js</li>
<li>Place the "tar-monasteries.js" in the /places/monasteries/js/ folder.</li></ol><p class="paragraph"><strong class="bold">Note:</strong> At the top of the JSON file there are two fields recording the number of monasteries in the list:</p><div class="code"><pre><span class="java-quote">"sEcho"</span>: 3,
<span class="java-quote">"iTotalRecords"</span>: 567,
<span class="java-quote">"iTotalDisplayRecords"</span>: 567,
<span class="java-quote">"aaData"</span>: [
....</pre></div><p class="paragraph">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.)
</p><h3 class="heading-h6"><a name="ProvidedforunrestrictedusebythespanclassnobrimgsrcsakairwikitoolimagesicklearrowgifaltexternallinktitleexternallinkahrefhttpwwwthliborgtargetrwikiexternalTibetanandHimalayanLibraryaspan" class="anchorpoint"></a><em class="italic">Provided for unrestricted use by the <span class="nobr"><img src="/" alt="external link: " title="external link"/><a href="http://www.thlib.org" target="rwikiexternal">Tibetan and Himalayan Library</a></span></em></h3>