BBC News Labs Documentation

Documentation for BBC News Labs APIs & #newsHACK events

Locator API Documentation

About Locator

The Locator service is a HTTP API that allows you to discover and ask geospatial questions about places and other entities such as postcodes, news regions, councils etc.


To use some of the BBC APIs you will need an API Key, which we have created for this event:


You should replace the text {{apikey}} in the examples with this key.

Core Concepts


A location entity is either a place or a post code for which we provide key properties such as a name, location (lat/lon point), country, timezone etc. Our location data is a subset of the Geonames gazetteer. We use the centre point of a postcode to determine it's location.

We provide mechanisms by which you may discover locations eg search, auto-complete, reverse-geocode (nearest location to a lat/lon).


We use the term 'details' to describe other data sets eg news regions, weather forecast locations, administrative geography etc. We often hold such data for our customers eg weather station locations for /weather.

We can answer geospatial queries that relate a location entity to a detail dataset eg "which BBC news region is Cardiff within".

Locator Postman Collection

If you install the free Postman REST Client you can import the Juicer API into using this URL:

This allows you to easily try out the API and explore how it works without writing any code.

You will need to configure an "Environment" within Postman to be able to make calls. You will need to set a host parameter with value and an apikey.

REST API Endpoints

1. Locations

Used to discover locations eg placename search, reverse-geocode.

Search for a placename{{apikey}}&vv=2&format=json&order=importance&filter=domestic&search=cardiff

Auto-complete a partial placename{{apikey}}&vv=2&format=json&order=importance&filter=domestic&auto=true&search=car

Search with co-ordinated (reverse-geocode){{apikey}}&vv=2&format=json&order=importance&filter=domestic&longitude=-3.18&latitude=51.48


You can filter and sort the articles returned from the articles endpoint. Parameters can be provided in the query string.

Available parameters:

  • search: a search term eg 'cardiff'
  • auto: when set to 'true' will return auto-complete results for the search value
  • longitude: longitude value for reverse-geocode request
  • latitude: latitude value for reverse-geocode request
  • format: reponse format of either 'xml' (default) or 'json'
  • order: sort the results by one of 'term' (default) or 'importance'
  • filter: a filter combines both place-types and countries. May be one of of 'domestic' (countries set to 'GB, GG, JE, IM', placetype set to 'settlement, airport') or 'international' (countries set to 'GB, GG, JE, IM', placetype set to 'settlement, airport, country')
  • place-types: filter by placetype eg 'settlement', 'airport', 'country', 'other'. You can specify multiple values eg 'airport,settlement'
  • countries: filter by country eg 'GB', 'FR'. You can specify multiple values eg 'GB,GG,JE,IM'
  • start: specify a result start offset (default 0)
  • rows: specify how many results to return (default 10)
  • vv: view version. use '2' for a friendlier result format

2. Location Details

Allows you to ask geospatial queries about a location.

URL<location Id>/details/<detailTypes>?apikey={{apikey}}&vv=2&format=json&op=<operator>


Nearest Rail Stations for a location 2YQ/details/railstation?apikey={{apikey}}&vv=2&format=json

BBC Tv & Radio Service(s) for a location,radio?apikey={{apikey}}&vv=2&format=json&operation=intersect

BBC News Organisation(s) for a location 2YQ/details/news-organisation?apikey={{apikey}}&vv=2&format=json&operation=intersect

Available parameters:

  • operation: geospatial operation. one of 'nearest' (default) or 'intersect'
  • start: specify a result start offset (default 0)
  • rows: specify how many results to return (default 10)
  • vv: view version. use '2' for a friendlier result format

Questions and Feedback

All comments are moderated for approval.