Unlock

Getting Started

Searching

Use the web service link, or Unlock Places API, to search for a placename like this:

        http://unlock.edina.ac.uk/ws/search?name=London&format=json
        

This shows results for places named (or containing) "London". By default, up to 20 results are shown. You can get more by adding, for example, &maxRows=100 to the end of the link.

You can see the results in different formats with the format parameter; use:

• format=kml to see KML for import into Google Earth,
• format=json for the Javascript Object Notation useful in web apps,
• format=txt for a comma-separated values file,
• format=xml, which is the default option.

A sample feature from the results of a search for "London" in JSON format look like this:

{
    "type": "Feature",
    "id": "4568139",
    "bbox": [-0.08855726569890976, 51.51305389404297, 
             -0.08945558220148087, 51.51361846923828],
    "properties": {
        "name": "City of London",
        "country": "United Kingdom",
        "featuretype": "third-order administrative division",
        "custodian": "GeoNames",
        "gazetteer": "GeoNames",
        "footprint": "http://unlock.edina.ac.uk/ws/footprintLookup?format=json&identifier=4568139"
    }
},
        

The bbox is the bounding box, a rough location for the place.

The footprint link may give a more detailed shape for the place-name. Some of our data sources only have points for places (like geonames.org); others have (generalised, or smoothed out) shapes for places (countries, regions in Natural Earth).

You can put a bounding box round your search and only show things that are inside it, or overlap with it. This is a search for places named London but only within an area around London, England:

http://unlock.edina.ac.uk/ws/search?name=London&minx=-1&maxx=1&miny=50&maxy=52&operator=within

Sources

Unlock has an open data gazetteer that is free for anyone to use. It searches through a number of data sets; places world-wide are included, and there is better detail for the UK.

How to use it

Please see the API Documentation and Example Queries pages for more detail on use of the web service. The web service provides more complicated spatial searches - for example, one can draw a buffer around a shape and search within 5 miles of it.

Unlock services are designed to be used as middleware re-used by another application - a script, or a web site. For example, the Archaeology Data Service uses Unlock to search for postcodes; the Go-Geo! data catalogue uses Unlock to search for place-names and look for data sets nearby.

Re-using the data

The open data sources are all available under some license that meets the terms of the Open Knowledge Definition. We keep the data attributed to its original sources.