Unlock places API — version 2.1

The Unlock places API was upgraded this week, with new functionality available from Tuesday, 19th January 2010.  An upgrade to the Postgres/PostGIS database has enabled a new ways of retrieving feature data from the gazetteer, so please visit the example queries page to try them out.

We welcome any feedback on the new features – and if there’s anything you’d like to see in future versions of Unlock, please let us know.  Alternatively, why not just get in touch to let us know how you’re using the service, we’d love to hear from you!

Full details of the changes are listed below the fold.

Full Text Search

All (text) searches now implement full text searching.

Full text search helps to extract more results from the database compared to the previous Unlock version. It is possible to search for complex place names such as ‘City of Edinburgh‘ or ‘Loch Lomond‘ and retrieve features which better match user’s search requirements.

Results ranking / sorting.

Search results are now sorted according to their importance / relevance through a complex set of rules.

When multiple features are returned with similar names, capitals and large cities are ranked higher than villages. Mountains are ranked higher than buildings (like schools, churches). While various feature types have a certain importance level on their own, user input also determines the result relevancy and can impact order of the returned search results.

For example, if user is searching for ‘Edinburgh‘ then features with exact name ‘Edinburgh‘ receive a ranking bonus over places where ‘Edinburgh‘ is only part of their name like ‘Edinburgh Hotel‘. Furthermore, if the search term was ‘Edinburgh Hotel‘ then a place named ‘Edinburgh Hotel‘ receives a bonus over a place called ‘Edinburgh City Hotel‘. Sometimes this bonus is not enough to overcome primary feature ranking (where city is far more important than a hotel for example).

Unique search and Closest match APIs.

Two new APIs allow for unique place searching and a single closest match search:

  • uniqueNameSearch?

If the same feature has multiple entries from different source data, only one record (from the most appropriate source) per real-world feature will be returned. Feature name is considered to be unique when it has a distinct/unique name, feature type and spatial footprint.

For example ‘Edinburgh‘, city, from OS gazetteer is equal to ‘Edinburgh‘, city, from the GeoNames gazetteer but ‘Edinburgh‘, administrative division, is not considered to be the same as ‘Edinburgh‘, city. At the moment this search deals with majority of feature name duplicates but it does not exclude them completely.

  • closestMatchSearch?

Will return the highest ranking feature (one single feature only) matching your search.
This search can be used for very quick and rough lookups and can be quite useful when used with the ‘country’ parameter.

Enhanced feature attribute data

Where available, feature data responses now contain additional attributes, including:

  • Centroid coordinates (EPSG4326)
  • Footprint area (km²) and perimeter (km) – where features have polygon footprints.
  • Elevation (m), population (singles) – this is for geonames data only
  • Scale of the gazetteer product (1:x)
  • 2 character ISO country code
  • List of alternative names

Additional geometries supported.

The following geometry types are now supported:

  • MultiPoint
  • LineString
  • MultiLineString

New filter by ‘country’ parameter.

Queries can now be restricted by a specific country, with a new parameter.

i.e. For all features with the name ‘Lincoln’ in the United Kingdom (or UK):

‘FeatureLookup’ API and unique feature addressing.

Features can now be retrieved individually by ID, using the featureLookup? API:


Features have unique URLs and can be addressed as:


Requesting key added to footprint URLs.

If a search is made with a valid key parameter, the key parameter is appended on to the footprint geometry URLs (found in the results data) automatically. 

Postgres upgraded to version 8.4., PostGIS upgraded to 1.4.

Various bug fixes, refactoring and speed improvements, updates to webpages with new example queries etc.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: