Unlock

Contact Us envelope image
Home > Unlock Places > API Documentation

API Documentation

The http://unlock.edina.ac.uk/ws/search API endpoint can be used in conjunction with the parameters below for the majority of searches:

General Search Parameters

Parameter

Description

name

One or more names (comma separated). Wildcards [*,?] allowed but only as part of an incomplete search string and cannot be used alone. Can also be used to search on an Unlock feature identifier rather than a place name as long as no gazetteer is specified. If you wish to search on an original gazetteer identifier, you have to specify the gazetteer the identifier is from as an extra parameter. Additionally can be used to search on a postcode.

format

One of xml, kml, json, georss or txt (defaults to xml) - the format of the place search results.

gazetteer

The place-name source to take locations from. The options are geonames, os, naturalearth, plplus or unlock which combines all the previous. unlock is the default. There is also the DEEP gazetteer of Old English place names, which is not searched by default. For more information about DEEP, click here: DEEP in Unlock Places

featureType

The feature type, or class of thing, that the place is. For example, Populated Place returns only settlements; Westminster returns constituency boundaries.

To help determine which feature types are supported the Unlock Places API can return a list of supported feature types which can be filtered by gazetteer and format. Valid format parameters are xml, json and txt (defaults to xml).

childTypes

If used in conjunction with featureType you can use childTypes to determine whether the results should include feature subtypes and sibling feature types. Boolean - accepts true or false only. Note that if this parameter is omitted, the default value is false, which means that no child features will be returned.

srs

The srs parameter can be used to change the spatial reference system of the output results. If not specified, results are returned with the default srs of 4326. Other possible values are 90013 and 27700.

Bounding Box Search Parameters

Parameter

Description

minx

the minimum longitude point of a bounding box.

maxx

the maximum longitude point of a bounding box.

miny

the minimum latitude point of a bounding box.

maxy

the maximum latitude point of a bounding box.

operator

The options are within and intersect. The results will therefore be entirely within, or overlapping with (intersecting), the bounding box.

Spatial Search Parameters

Parameter

Description

buffer

search within distance from bounding box or feature ID. In metres.

spatialMask

search within this "mask" - a shape identified by its Unlock ID.

realSpatial

yes or no - used with spatialMask - do the search with the detail of the shape rather than just drawing a bounding box round it, as happens by default.

country

In conjunction with the name parameter, the country parameter lets you limit your search results to a particular country. As an alternative to using this parameter, you can also supply the country you wish to constrain your search to after your name search term separated by a comma.

Number of Results Parameters

Parameter

Description

maxRows

The maximum number of results to return. Defaults to 20. Cannot exceed 1000. [Optional].

startRow

The row to start results display from. Defaults to 1. [Optional].

Footprint Lookup Parameters

The API endpoint http://unlock.edina.ac.uk/ws/footprintLookup returns the footprint of the polygon associated with an Unlock ID. It accepts the following parameters:

Parameter

Description

identifier

The Unlock ID of the feature you wish to search for. Mandatory.

gazetteer

The place-name source to take locations from. The options are geonames, os, naturalearth, plplus or unlock which combines all the previous. unlock is the default. There is also the DEEP gazetteer of Old English place names, which is not searched by default. For more information about DEEP, click here: DEEP in Unlock Places

format

One of xml, kml, json, georss or txt (defaults to xml).

srs

The srs parameter can be used to change the spatial reference system of the output results. If not specified, results are returned with the default srs of 4326. Other possible values are 90013 and 27700.

Distance Between Parameters

The API endpoint http://unlock.edina.ac.uk/ws/distanceBetween returns the distance in metres between two features specified by their Unlock IDs. The following parameters are required:

Parameter

Description

idA

The Unlock ID of the first feature. Mandatory.

idB

The Unlock ID of the second feature. Mandatory.

Name Index Search Parameters

The API endpoint http://unlock.edina.ac.uk/ws/nameIndexSearch is a lightweight approach (in comparison to carrying out a wildcard search against the search endpoint) that can be used to generate full place name options from four or more letters. The following parameters are accepted:

Parameter

Description

name

The beginning of a place name you wish to see autocomplete options for. Note that it has to be at least 4 characters long. Mandatory.

format

One of xml, kml, json, georss or txt (defaults to xml).

callback

This optional parameter only applies when the format parameter is set to json. It allows you to specify a callback name and returns JSONP.