API Documentation
Unlock Places
Introduction
Unlock places gazetteer service can return bounding boxes and footprint geometries for approximately 10 million features from Ordnance Survey and GeoNames data. Queries to the web services are RESTful HTTP GET requests to a number of different APIs, using URL parameters to specify the search parameters and return format.
Looking at the example queries is a good way to get an idea of what's possible. Our Getting started guide sets out the basics in a bit more detail. Otherwise, read on.
http://unlock.edina.ac.uk/ws/[chosen API here]
Where [chosen API here] is one of the following operations:
| API | Description | |
|---|---|---|
| nameSearch | Search for features by name | |
| nameAndFeatureSearch | Search for features by name and feature type | |
| spatialNameSearch | Search for features by name, within a bounding box | |
| spatialFeatureSearch | Search for features by feature type, within a bounding box | |
| closestMatchSearch | Search for features by name, returning the closest match | |
| uniqueNameSearch | Search for features by name, return only one result per feature* | |
| postCodeSearch | Search for post code - requires registration key | |
| footprintLookup | Retrieve a feature's footprint by identifier | |
| featureLookup | Retrieve a specific feature by identifier | |
| supportedFeatureTypes | List the supported feature types | |
* This query removes duplicate features from different gazetteers, choosing feature data from the most relevant. |
||
Key Registration
Unlock Places currently features two data sources, Ordnance Survey and GeoNames. Registration for access to Ordnance Survey data is available above. Searching without a key parameter will return results GeoNames only. Access keys are bound to both your Digimap username and IP address.
Querying
Queries to the Unlock web wervices are made as a GET request to the appropriate API. For example, a simple query to search for features with the name 'Edinburgh', with all other parameters as defaults:
http://unlock.edina.ac.uk/ws/nameSearch?&name=Edinburgh
Postcode searches do require a key (as the data is from Ordnance Survey's Code-Point database). An example postcode search is:
http://unlock.edina.ac.uk/ws/postCodeSearch?postCode=EH9 1PR&key=[your key here]
Parameters
Various parameters are mandatory or optional for the different search types. The following table lists the parameters:
| Parameter | Value | Type | Description |
|---|---|---|---|
| key | A registered API key. The presented key is mapped to the IP address of the request. | String | Unlock Web Services authentication. |
| name | One or more names (comma separated). Wildcards [*,?] allowed but only as part of an incomplete search string and cannot be used alone. | String | Search for a feature by name. |
| featureType | One or more feature types (comma separated) from the Supported Feature Types. Required for feature type searches. | String | Search by Feature Type. |
| gazetteer | One or more gazetteers (comma separated) from the available gazetteers. Currently 'os' and 'geonames'. Defaults to 'geonames' when no key present. Optional. | String | Gazetteer (data source) to use. |
| format | One of xml, html, kml, json, georss, txt. Defaults to xml. Optional. | String | The format of the results returned. See the formats section below for further details. |
| startRow | The row to start results display from. Defaults to 1. Optional. | Integer | Enables paged results. |
| maxRows | The maximum number of results to return. Defaults to 20. Cannot exceed 1000. Optional. | Integer | Enables paged results. |
| country | A country name, to filter results by. Optional. | String | Retrieves results from specified country only. |
| postCode | A Postcode Unit. Required for postcode searches. For more information on Postcode units please consult the UK Government Data Standards Catalogue. | String | Search for Postcode Units. |
| identifier | Required for footprint lookup searches. An identifier is returned as part of all request responses, for example, from a feature name search. | Integer | Search for a known Unlock feature identifier. |
| maxx | A lat/long floating point value giving the maximum longitude point of a bounding box. Required for spatial searches. | Float | The maxx point of a bounding box. |
| minx | A lat/long floating point value giving the minimum longitude point of a bounding box. Required for spatial searches. | Float | The minx point of a bounding box. |
| maxy | A lat/long floating point value giving the maximum latitude point of a bounding box. Required for spatial searches. | Float | The maxy point of a bounding box. |
| miny | A lat/long floating point value giving the minimum latitude point of a bounding box. Required for spatial searches. | Float | The miny point of a bounding box. |
| operator | A spatial operator for spatial searches, 'within' and 'intersect' operators are supported. Required for spatial searches. | String | Enables spatial searching within/intersecting a bounding box. |
| count | Whether to provide a total results count, either 'yes or 'no'. Defaults to 'yes'. If 'no', results count set to -1. Optional, for use with nameSearch. | String | Can speed up open searches with large result sets. |
| callback | A callback function name to wrap JSON output, for use in cross-domain AJAX scripting e.g jQuery's JSONP function. Optional, for use with JSON output format. | String | Wraps JSON output in a callback function. |
| srs | A spatial reference system to use when returning feature coordinates Optional, defaults to 4326 (can be 4326, 27700 or 900913) | String | Can be used to re-project coordinates |
Output Formats
The format parameter sets the output format, and can be one of:
| Parameter | Format |
|---|---|
| xml | For a simple XML format |
| html | For HTML output |
| kml | For KML 2.2 |
| json | For GeoJSON 1.0 |
| georss | For GeoRSS-Simple 1.0 (Atom) |
| txt | For plain-text format |
http://unlock.edina.ac.uk/ws/nameSearch?name=London&format=json
Feature Footprints
Each feature in the gazetteer has a footprint geometry, which may be a point, polygon, or multi-polygon geometry. These can be retrieved by performing a second query using the feature's ID (first retrieved by a standard feature search).
The polygon for the postcode searched for above (key required) is:
http://unlock.edina.ac.uk/ws/footprintLookup?identifier=108274&key=[your key here]
Wrapping JSON ouput in a callback function
The callback parameter (callback=function) wraps the JSON output text in parentheses and a function name of your choosing. Callbacks are particularly useful (as explained here) for use with web service requests in client-side JavaScript / AJAX. Normally browser security restrictions prevent using the XMLHttpRequest object loading files across domains.
Using JSON and callbacks, you can place the Unlock Web Service request inside a <script> tag, and operate on the results with a function elsewhere in the JavaScript code on your page.
Quick Links
Unlock also supports several 'quick links' for simple searching. More information can be found on how to use quick links here.
Text/Places
The API for Unlock text is just one function. Make a POST request to this url with the parameters shown below: http://unlock.edina.ac.uk/text/places
| Parameter | Value | Type | Description |
|---|---|---|---|
| document | Text contents to be geoparsed. | String | This may be plain text, HTML or XML - specified by the "type" parameter |
| type | One of ['plain','html','xml'] | String | |
| format | One of ['json','kml','basic'] | String | The output format for the set of results |
| gazetteer | Either 'geonames' or 'os' | String | The gazetteer to be used to resolve the placename locations. If requesting OS data, you must also specify an API key. |
| key | A registered API key. The presented key is mapped to the IP address of the request. | String | Unlock Web Services authentication. Only needed for OS data. |
You can use a command-line client, such as curl, to make the POST request like so:
curl -d type=plain -d "document=Carnock is a small town in Fife near Dunfermline" / -d gazetteer=geonames http://unlock.edina.ac.uk/text/places
