Unlock - code samples

Code samples

Python

A Python client package is available to easily access the Unlock API.

Source Code


        easy_install unlock

        from unlock import Places
        
        p = Places()
        xml = p.nameSearch('Edinburgh')

Download the Unlock client package from PyPi. There’s also a simple interface to the geoparser, Unlock Text, in there.

JavaScript

Simple search using a Javascript callback

The example below is an entire webpage, which requests a list of 10 features (by name) using a Javascript function. When the JSON is returned, it is wrapped in a callback function which is added to the page and executed. The callback displays the list of features and creates hyperlinks to each feature's footprint.

Demo

Source Code


<html>
<head>
<script type="text/javascript">
<!--
/**
 * Lists features from the JSON feed by creating a
 * new 'ul' element in the DOM.  Each bullet is the
 * title of one feature, and contains a hyperlink
 * to that feature's footprint URL.
 *
 * @param {JSON} json is the JSON object retrieved from Unlock.
 */
function listFeatures(json) {
    // Clear any information displayed under the "data" div.
    removeOldResults();
    var ul = document.createElement('ul');

    for (var i = 0; i < json.features.length; i  ) {
        var entry = json.features[i];
        var footprintUrl = json.features[i].properties.footprint;
    
        var li = document.createElement('li');
        var a = document.createElement('a');
        a.href = footprintUrl;
        a.target = '_blank';

        var txt = document.createTextNode(json.features[i].properties.name);
        a.appendChild(txt);
        li.appendChild(a);
        ul.appendChild(li);
    }

    // Add the bullet list of features.
    document.getElementById('data').appendChild(ul);

    // Re-enable the search button.
    var search_button = document.getElementById('search_button');
    search_button.removeAttribute('disabled');
}

/**
 * Called when the user clicks the 'Search' button to
 * retrieve a feature's JSON feed.  Creates a new script
 * element in the DOM whose source is the JSON feed, and
 * specifies the callback function is 'listFeatures' (above).
 *
 * @param {String} query is the feature name to be retrieved
 */
function search(query) {
    // Delete any previous JSON script nodes.
    removeOldJSONScriptNodes();
    // Clear any old data to prepare to display the Loading... message.
    removeOldResults();

    // Show a "Loading..." indicator.
    var div = document.getElementById('data');
    var p = document.createElement('p');	
    p.appendChild(document.createTextNode('Loading...'));
    div.appendChild(p);

    // Disable the search button.
    var search_button = document.getElementById('search_button');
    search_button.disabled = 'true';

    // Retrieve the JSON feed.
    var script = document.createElement('script');
    script.setAttribute('src', 'http://unlock.edina.ac.uk/ws'  
                      '/nameSearch?format=json&maxRows=10&callback=listFeatures'  
				      '&name='   query);
    script.setAttribute('id', 'jsonScript');
    script.setAttribute('type', 'text/javascript');
    document.documentElement.firstChild.appendChild(script);
}

/**
 * Deletes any old script elements which have been created by previous calls
 * to search().
 */
function removeOldJSONScriptNodes() {
    var jsonScript = document.getElementById('jsonScript');
    if (jsonScript) {
        jsonScript.parentNode.removeChild(jsonScript);
    }
}

/**
 * Deletes pre-existing children of the data div from the page. The data div 
 * may contain a "Loading..." message, or the results of a previous query. 
 * This old data should be removed before displaying new data.
 */
function removeOldResults() {
    var div = document.getElementById('data');
    if (div.firstChild) {
        div.removeChild(div.firstChild);
    }
}

//-->
</script>
</head>

<body>
    <form onsubmit="return false">
        <p>Feature name: <input name="feature_name"></input>
        <button id='search_button' onclick="search(this.form.feature_name.value);">Search</button>
        </p>
    </form>
    <div id="data"></div>
</body>
</html>

Auto-suggest search using jQuery

Using the jQuery library, in combination with the jquery.autocomplete.js plugin, the code below makes a request to Unlock's search API and suggests results. It can be embedded on to any web page, giving your application access to the Unlock gazetteer.

Demo

This auto-suggest search can be found on the Unlock Places page.

Source Code


    var server = "http://unlock.edina.ac.uk/ws/"

    $(document).ready(function() {
        $("#autoNameField").autocomplete(server+"nameSearch",{    
             dataType: 'jsonp',
             parse: function(data){
    	  		var rows = new Array();
    	     	data = data.features;
    	     	for(var i=0; i<data.length; i++){
    	       		rows[i] = { data:data[i], value:data[i].properties.name, result:data[i].properties.name };
    	       	}
    	       	return rows;
    	     },
    	     
     	     formatItem: function(row, i, n) {
     	        return row.properties.name + ", " +row.properties.country
     	        + "<br/><span style='font-size:70%'>"
     	        + row.properties.featuretype + "<span>";
     	     },
    	     
    	     extraParams: {
    	        // Unlock doesn't use 'q' and 'limit', the autocomplete plugin defaults, so we blank them out.
    	        q: '',
    	        limit: '',
    	        format: 'json', // Retrieve the results in JSON format
    	        maxRows: 10, // Limit the number of results to 10
    	        count: 'no', // Prevent Unlock from counting the total possible results (faster)
    	        name: function () { return $("#autoNameField").val() }
    	     },
    	     max: 10
        });
    });