How to Use Our API

As Adrian notes in the API release post, this is the first version of our proof-of-concept API. We’ll do our best not to change the content structure significantly, but it may change to some degree. At this stage we can’t make any promises about uptime and stability.

In my last post, I talked about our technical approach and noted that the original list of providers we found with WW1 content was so dominated by Solr, that we took the decision to base both our API syntax and the structure of the returned metadata around that of Solr. As a result of these origins, there are a number of query options which pass directly through to Solr sources but do not or cannot translate to other providers.

Issuing Queries

A simple search for a single subject term would therefore be (in this case, a search for bread)

http://discovery.ac.uk/ww1/api/?q=bread

Where possible behind the scenes, we have already constrained searches on each individual provider to their WW1 collections. In many cases this is done by adding keywords such as “first world” to any search term entered above after the search has been issued.

Multiple search terms must currently be separated by + in order to be passed through successfully to all providers

http://discovery.ac.uk/ww1/api/?q=bread+milk

Passing &fl= will restrict the fields returned from solr providers to the comma separated list:

http://discovery.ac.uk/ww1/api/?q=bread&fl=title,subject

You can also restrict the number of records returned by each provider (default 12) and the timeout for the providers (currently 10 seconds) using &records= and &timeout=

http://discovery.ac.uk/ww1/api/?q=bread&records=5&timeout=20

You can get facet counts for the fields in our API output (i.e. after they have been mapped to our common metadata scheme) by appending &facet=true&facet.fields=

http://discovery.ac.uk/ww1/api/?q=bread&facet=true&facet.fields=dc.subject

Issuing an empty query will return metadata about the sources which are currently in use, including their internal short names

http://discovery.ac.uk/ww1/api/

Which can then be used to restrict your query to run on a comma separated list of internal short-names using &sources=

http://discovery.ac.uk/ww1/api/?q=bread&sources=europeana,nationalmaritime

If you want JSON instead of Solr XML, you can use &wt=json

http://discovery.ac.uk/ww1/api/?q=bread&wt=json

And additionally, if you would prefer a more easily-parseable XML output, you can use &wt=swapNameAndType

http://discovery.ac.uk/ww1/api/?q=bread&wt=swapNameAndType

For a quick and basic visualisation of the metadata, add &stylesheet=demoresults.xsl — doing this without a query will prompt you to enter one

http://discovery.ac.uk/ww1/api/?stylesheet=demoresults.xsl

http://discovery.ac.uk/ww1/api/?q=bread&stylesheet=demoresults.xsl

Returned results

A header has been added to the Solr response containing details of the various sources. Metadata fields from each provider have been mapped to a common metadata scheme where the relationship between that field and a corresponding field in the common scheme is known; otherwise, the provider’s short name has been prepended to the metadata field name in the output. The Solr doc items have been modified to contain a reference to the provider from which they have originated.

Tags: aggregation, api, data format, documentation, information standards, metadata, outputs, solr, ukdiscovery, ww1, ww1mimas