Developers

Public API

If you want to use our data, we’ve provided an API to allow you to query it for use in your own applications. There are a number of endpoints: four which allow you to browse features (ie. buildings, parks, and other places in Whitechapel), documents, images, and media or return individual records in these categories; and a second set of four which allow you to chain queries. All endpoints are read-only, and if you visit them using your browser, you'll get a human-friendly html representation of what each one will send back to you.

Browse Endpoints

https://surveyoflondon.org/api/v1/features/
Returns features as geoJSON

https://surveyoflondon.org/api/v1/documents/
Returns documents as JSON

https://surveyoflondon.org/api/v1/images/
Returns images as JSON

https://surveyoflondon.org/api/v1/media/
Returns media items as JSON

To retrieve a single record (for example, for a feature):
https://surveyoflondon.org/api/v1/features/10/

Or a document:
https://surveyoflondon.org/api/v1/documents/1/

Query Endpoints

https://surveyoflondon.org/api/v1/query/features/
https://surveyoflondon.org/api/v1/query/documents/
https://surveyoflondon.org/api/v1/query/images/
https://surveyoflondon.org/api/v1/query/media/

The features endpoint accepts the following parameters:

  • author: The author of a document, image, or media item attached to a feature (number). Example: author=2
  • categories: A list of categories to which features belong (a comma-separated list of numbers). Example: categories=2,4
  • tags: A list of tags that have been attached to a feature (a comma-separated list of text strings). Example: tags=cholera,baths
  • year_range: The years of construction between which you want to search (either a single year value, or a comma-separated list of two years). If only one year is given, everything built since that year is returned. Example: year_range=1974,2010
  • q: A free text query of the name of the feature, the street it sits upon, or the title or content of the documents, images, and media attached to it (string). Example: q=davis

So, to return every feature with contributions from author 2, in categories 14 and 12, tagged ‘baths’ and ‘cholera’, and built between 1800 and 2000:
https://surveyoflondon.org/api/v1/query/features/?author=2&categories=14,12&tags=baths,cholera&year_range=1800,2000

The documents, images, and media endpoints accept most of the above parameters, though categories are omitted, and year_range is replaced by date_range. This allows you to narrow contributions by date of submission using either a single date value in the format YYYY-MM-DD, or a comma-separated list of two dates, for example, date_range=2016-06-01,2016-07-30.

So, to return every document containing the string 'baths' by author 2 and contributed between 24th June and 24th July:
https://surveyoflondon.org/api/v1/query/documents/?q=baths&author=2&date_range=2016-06-24,2016-07-24

For all endpoints, results are paginated by 20 records by default. To change the page, append page=<page_no> (ie. page=2) to the query string. To change the number of records returned per page append page_size=<no_records> (ie. page_size=100). For performance reasons, the maximum number of records the API will return is 100.

We’d love feedback on this, and if there’s a feature you’d like to see added, please email Duncan Hay at d.hay@ucl.ac.uk. Most of all, if you make anything using the API, let us know - we want the Survey of London Whitechapel data to be a resource for others for others to use, and we’d love to see what you build.