For Developers – OB API details

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 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 following servlet detail 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 to always specify a “count” parameter, as the default is all results.

If you would like the returned a 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 in this case ignored.

There are some caveats. The servlet will not return lists of more than 1000 ids, or zip files of more than 50 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]

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”.