API Functionality

If you’re interested in how the client-side interface talks to the server-side API, and in addressing and re-using Old Bailey data directly, the easiest approach is to explore the Query URL and Zip URL links. But details of the server-side search and retrieval functions are also available at the following URLs:

i) http://www.oldbaileyonline.org/obapi/terms

This servlet always returns a JSON object describing the fields which can be queried, their types, and their possible values. It is used to construct the search form in the Javascript Demonstrator interface. The structure of the JSON object is intended to be self explanatory, but the following servlet details the process.

ii) http://www.oldbaileyonline.org/obapi/ob

This servlet receives search terms and additional instructions as HTML parameters. It returns either a JSON object representing a result set, or a ZIP file of texts from the result set.

Search terms are specified as follows:

• term[term number]=[field]_[term]

Results are paged as follows:

• start=[result to start from]
• count=[number of results to return]

It is a good idea always to specify a “count” parameter, as the default is all results.

If you would like the returned JSON object to include a frequency table of terms in the results, you can specify the field you would like to examine:

• breakdown=[field]

If you would like the full text of the results returned in a zip file, you can specify:

• return=zip

For example:

http://www.oldbaileyonline.org/obapi/ob?term0=trialtext_sheffield&term1=offcat_deception&breakdown=offsubcat&count=10&start=0

will return a JSON object representing a result set where every trial contains the term “sheffield”, and an offence category of “deception”. The object will also offer a frequency table of offence subcategories within this result set. The hit list returned will start at the first result and continue for ten results.

Alternatively:

http://www.oldbaileyonline.org/obapi/ob?term0=trialtext_sheffield&term1=offcat_deception&breakdown=offsubcat&count=10&start=0&return=zip

will perform the same search as above, but return a zip file containing the first ten trials of the result set. The “breakdown” parameter is ignored in this case.

There are some caveats. The servlet will not return lists of more than 1000 IDs, or zip files of more than 10 trials. Frequency tables of terms are also curtailed (and inaccurate) if they contain more than 1000 distinct terms.

iii) http://www.oldbaileyonline.org/obapi/text

This servlet receives the ID of a single trial, and optionally a list of words to highlight as HTML parameters. It returns the XML of the requested trial.

• id=[trial id]
• highlightTerms=[terms to highlight]

For example:

http://www.oldbaileyonline.org/obapi/text?div=t17690112-9&highlightTerms=sheffield+fraud

will return the XML of the trial t17690112-9, with <span> tags around the words “sheffield” and “fraud”.