Getting Started
Places
Unlock services are middleware, which means they're intended to be used by another application - a script, or a web site.
Unlock places gazetteer search can be used in "real time" - looking up the coordinates of postcodes to search against your own database - or in "batch mode", using the gazetteer to georeference a large collection of media files.
Use of the API starts as simply as making a request for a web address to search for a placename:
http://unlock.edina.ac.uk/ws/nameSearch?name=London&format=json
This shows results for places named (or containing) "London". By default, up to 20 results are shown though the total available may be greater.
You can see the results in different formats by using a different format parameter
- 'html' to see results on a web page, with individual features on a map
- 'kml' to see KML data suitable for import into Google Earth
- 'json' for a Javascript Object Notation suitable for re-use in web applications
- 'xml', which is the default option.
Here's a sample of one of the results in JSON format from the link above.
{
"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 property is an approximate location for the place.
The footprint link may provide more detailed location information about the feature's spatial footprint. Please note: GeoNames data will return only Point geometry.
You can limit the "extent" of the search with a "bounding box" - the next example shows a search for places named London only within an area around London, England:
What's next?
Please see the API Documentation and Example Queries pages. These examples should help you build requests to suit your needs.
How Accurate Is It?
Our geonames.org open data only provides "point data" - latitude,longitude coordinate pairs which represent the approximate centre of a named place. Our detailed Ordnance Survey dataset for academic use has detailed "footprints" or shapes for places.
