The Locating London's Past API

Locating London's Past (http://www.locatinglondon.org/) is a website allowing analysis of historical data using the Google Maps API. It allows a user to search data relating to early modern and eighteenth-century London, and to map the results on historical or modern maps, with a degree of GIS-style functionality.

Note: If you would like to experiment with the geographical data, you might want to concentrate on just the 'molaindex' data, and the 'geo_coordinates' field. For example, a request to http://www.locatinglondon.org/data?index=molaindex&term1=kw_geo_description__southwark will give you a chunk of JSON data representing all the places we know about with 'Southwark' in their description. The 'geo_coordinates' field for each hit contains WGS84 polygon data which can be placed straight on to a Google Map.

The API is based around three servlets:

Each servlet understands a variety of GET parameters, and they return data variously in JSON, XML and HTML.

1. http://www.locatinglondon.org/terms

'terms' returns the possible search terms for each data index. It can return data in JSON or HTML. It understands two parameters: 'index' and 'format'.

Parameter Explanation Possible Values
index Specifies which index to interrogate. Required. molaindex, cmh_ht, cmh_pd, cmh_ad, cmh_ps, ob, ahdsfsp, ppop, mola_g, mola_cp ll_guild, ll_coroner, ll_criminal, ll_poor, west_poll, west_rate, ahdsdir, pcc, fire, lsdspar, ahdsitp, ahdsmar, smdswhr
format Specifies the format of the data to be returned. Required. JSON, HTML

Examples:

http://www.locatinglondon.org/terms?index=ob&format=HTML returns a search form for the Old Bailey data set in HTML. You can actually click on this link in a browser and the HTML should be displayed correctly, although it wont return any results unless you actually integrate the HTML into some kind of JavaScript application.

http://www.locatinglondon.org/terms?index=pcc&format=JSON returns the search fields and terms for the Canterbury Wills data in JSON format. Try it; your browser should display the JSON. The structure of the JSON is fairly self explanatory.

Output:

The JSON output is a list of fields. Each field has a name, a type, and optionally a list of possible values (terms).

A field of type 'text' can be queried with any text string. If the field name begins with 'kw_', it is a keyword field, and will return a hit if a word queried against it occurs anywhere within the field contents. If the field name does not begin with 'kw_', the field will only return a hit if the query text matches it exactly, and in its entirety. 'text' type fields would typically be represented by a text box.

A field of type 'select' can only be queried with the terms provided in its 'terms' list. 'select' type fields would typically be represented by a drop down menu.

A field of type 'range' can be queried with a maximum and minimum value from the terms provided. 'range' type fields would typically be represented by two drop down menus: one for a minimum value and one for a maximum value.

Note: When an application comes to pose a query to the 'data' servlet using a 'range' field, a minimum value should be given with 'from_' prefixed before the field name, and a maximum value should be given with 'to_' prefixed before the field name. For example, 'term1=from_year__1742&term2=to_year__1750'.

All of the indexes, fields and terms use abbreviated names. These can be converted into human readable strings using the file http://www.locatinglondon.org/display.js. Include the display.js file in your application and call the function 'display'. The first argument should be the string to convert. The following three arguments are optional, and allow selective conversion of the string based on whether the string is associated with a specific index, application context, or is a term belonging to a specific field.

2. http://www.locatinglondon.org/data

'data' returns search results in response to submitted queries. The results are always returned as JSON. The JSON is fairly complex, but should be human-readable to a large extent. It understands many parameters and is the most complex servlet.

Requests to 'data' must contain an 'index' parameter, to specify which data shall be consulted. The search criteria are specified by a series of parameters beginning 'term', and followed by a number. For example, 'term1', 'term2', 'term3' etc. The value of these parameters should be a valid field name (obtained from the 'terms' servlet), followed by two underscores, followed by the desired value of the field. For example, 'term1=kw_fulltext__dagger'.

It is also possible to request a summary of the results grouped by specific field. This is done via the 'breakdown' parameter. For example, 'breakdown=geo_parishes' will group the results by Parish.

Paging of results can be controlled by the 'pagehits' and 'skip' parameters.

Parameter Explanation Possible Values
index Specifies which index to interrogate. Required. molaindex, cmh_ht, cmh_pd, cmh_ad, cmh_ps, ob, ahdsfsp, ppop, mola_g, mola_cp ll_guild, ll_coroner, ll_criminal, ll_poor, west_poll, west_rate, ahdsdir, pcc, fire, lsdspar, ahdsitp, ahdsmar, smdswhr
term[n] Specifies the search criteria. Search criteria are specified by a series of parameters beginning 'term', and followed by a number. For example, 'term1', 'term2', 'term3' etc. Optional. Any number of terms can be specified, including none. Field names obtained from the 'terms' servlet, and URL Encoded values, separated by two underscores ('__'). For example, 'term0=kw_geo_description__stepney' .
breakdown Requests a summary of the results grouped by the specified field. Optional. A field name obtained from the 'terms' servlet.
pagehits Specifies how many results to return. The default is ten. Optional. Any integer from 1 to 5000.
skip Specifies how many results at the start of the set to skip. Useful for paging results. So if you wanted to see a fourth page of ten results, you would set 'pagehits' to '10' and 'skip' to '30'. The default is zero. Optional. Any integer, although specifying a number above the total number of hits will return no results.

Examples:

http://www.locatinglondon.org/data?index=ob&term1=kw_fulltext__dagger&term2=from_year__1742 returns JSON results from the Old Bailey data set which contain the word 'dagger' and date from year 1742.

http://www.locatinglondon.org/data?index=molaindex&term0=kw_geo_description__stepney&pagehits=20&skip=20 returns JSON results from the MOLA index of places which contain the word 'Stepney' in their description. Returns 20 hits, starting at hit 21.

http://www.locatinglondon.org/data?index=ob&term1=offsubcat__murder&breakdown=geo_parishes returns JSON results from the Old Bailey data where the offence subcategory is 'murder', and groups those results by Parish.

Output:

The top level of the JSON includes the fields 'total', which is the total number of hits, 'hits', which are the hits themselves, and the 'breakdown', if requested.

The 'hits' field consists of a JSON list of all the hits. Each hit consists of named fields. These can be identified and interpreted using http://www.locatinglondon.org/display.js. An interesting field is 'geo_coordinates'. These are the geographical coordinates of the hit. They are in the WGS84 coordinate system and describe a polygon. If they are given to a Google Maps instance, they can be used to draw a polygon on a world map representing the hit.

The 'breakdown' field consists of a JSON list of all the terms relevant to the breakdown. For example, if the field to be broken down was 'geo_parishes', it would be a list of Parishes. Each term will have a total number of hits associated with it, and where applicable geographic data corresponding to that term, for example the outline of the relevant Parish.

3. http://www.locatinglondon.org/text

'text' returns TEI-style xml, for data sets which are based around full-text sources (as opposed to database-style sources). The results are always returned as XML. It understands three parameters: 'file', 'div1id' and 'placeid'.

Parameter Explanation Possible Values
file The internal path of the XML file to be returned. Required. Obtainable from the 'file' field returned by the 'data' servlet.
div1id The subdivision of the XML file to be returned. Required. Obtainable from the 'div1id' field returned by the 'data' servlet.
placeid A place instance to highlight in the returned XML. Optional. Obtainable from the 'id' field returned by the 'data' servlet.

Examples:

http://www.locatinglondon.org/text?file=ob%2F16740429.xml&div1id=t16740429-9 returns XML for the div id 't16740429-9' from Old Bailey file 'ob/16740429.xml'.

http://www.locatinglondon.org/text?file=ob%2F17750531.xml&div1id=t17750531-3&placeid=t17750531-3-crimeloc17 returns XML for trial 't17750531-3', with the place name 't17750531-3-crimeloc17' highlighted.

Output:

The returned XML uses TEI-style tags, but omits the TEI declaration. The highlighted place element will contain the attribute 'highlight="true"'. A basic style sheet for converting the output to HTML exists here: http://www.locatinglondon.org/fulltext.xsl

Contact Us

The HRI developer currently responsible for maintaining the Locating London API is Jamie McLaughlin. Technical support may also be also be requested from hri-support@sheffield.ac.uk. Further information on HRI Digital can be found at http://hridigital.shef.ac.uk/.