Library Hub Discover APIs for Developers

Library Hub Discover has several APIs available. We've tried to keep the Z39.50 and SRU APIs compatible with the legacy Copac services and we have created a new JSON API.

Z39.50

The most vital information you need to know to get your Z39.50 client connected to the Discover Z39.50 service.
Address: discover.libraryhub.jisc.ac.uk
Port: 210
Database name: DISCOVER
Record syntax: XML or SUTRS
No username or password are required.

Record Syntaxes

XML and SUTRS are supported. There are no plans to deliver MARC records as part of the Library Hub Discover service. The XML records conform to the MODS Schema.

Record Character Set

The records use the Unicode character set in UTF-8 encoding.

Element Set Names

Records can be retrieved in either Brief (B) or Full (F) form. The default is Full.

Other ESNs available for SUTRS records only are:

REF
This will present records in a form suitable for loading into a personal bibliographic reference manager such as Papyrus or Endnote.
PRINTF
This is the same as the "Print format (Full)" download available from the Export option of the Discover web interface.
PRINTB
This is the same as the "Print format (Brief)" download available from the Export option of the Discover web interface.
TAGGEDF
This is the same as the "Tagged (Full)" download available from the Export option of the Discover web interface.
TAGGEDB
This is the same as the "Tagged (Brief)" download available from the Export option of the Discover web interface.

Supported Use Attributes

Only the BIB-1 attribute set is supported. The attributes available for searching are as follows:

  • Personal name (1)
  • Corporate name (2)
  • Conference name (3)
  • Title (4 & 1097)
  • ISBN (7)
  • ISSN (8)
  • Subject (21 & 1099)
  • Publication date (30, 31 & 1102); a numeric year is expected, though you can search for a range with a term like "1900-1920" (minus the quotes)
  • Language (54 & 1105); Use language codes such as fre (French) or ger (German) etc. You can get language name to code conversions from the MARC code list for languages.
  • NBK Institution ID (56)
  • Geographic name (58)
  • Publisher place (59)
  • Abstract & table of contents (62)
  • Notes (63)
  • Name (1002)
  • Author (1003 & 1098)
  • Personal name—author (1004)
  • Corporate name—author (1005)
  • Conference name—author (1006)
  • Standard number; e.g. ISBN, ISSN, ISMN, etc. (1007)
  • Most keyword fields (1016 & 1017)
  • Bibliographic encoding level (1021)
  • Map scale (1024); a numeric term is expected, though you can search for a range with a term like "35000-50000" (minus the quotes)
  • Corporate subject (1073)
  • Conference subject (1074)
  • Publisher name (1018 & 1101)

SRU

The SRU service is available at http://discover.libraryhub.jisc.ac.uk:210/discover.

As an example, the following SRU URL performs a search for "railway architecture" and requests 1 record: http://discover.libraryhub.jisc.ac.uk:210/discover?operation=searchRetrieve&version=1.1&query=dc.title%3d%22railway+architecture%22&maximumRecords=1&recordSchema=mods.

For information on how to format the SRU query look at the CQL documentation on the SRU website.

Supported indexes

The following CQL indexes are supported for searching:

  • cql.serverChoice
  • rec.id
  • dc.title
  • dc.subject
  • dc.author
  • dc.creator
  • dc.publisher
  • dc.description
  • dc.date
  • dc.language
  • bath.name
  • bath.personalName
  • bath.corporateName
  • bath.conferenceName
  • bath.isbn
  • bath.issn
  • bath.geographicName
  • bath.notes

JSON

The Discover web search can be used as a JSON API. If you include a format=json parameter in the url then you'll receive a JSON response instead of HTML. Search Results are delivered in pages of 25 records. A typical response (with the bibliographic records elided for clarity) is show below

{
 "hits": 104,
 "next-page": "WzM3Ljc4Mzk2Niw5MDU2Nzc4XQ==",
 "records": [ ... ]
}
    

The JSON object returned contains three values; an array of records, the number of search hits and a next-page token. To get the next page of results the next-page token should be appended to the search url, e.g. &next-page=<next-page-token>.

URL Endpoint

https://discover.libraryhub.jisc.ac.uk/search

Fields available for searching

The fields listed below are the fields in our Advanced Search form. You can create a search url for this API by using the Advanced Search form.

Fields available for searching in the query string part of the url.
Field name Type of field Comments
title keyword The title of a work.
author keyword The creator or editor of a work. Our records contain names in a variety of styles; not all have the full given names. Searching for a surname with the initials in the form dickens, c should find records that have the name in full or with just the initials.
subject keyword Subject terms. Our records contain a variety of subject terms from LCSH to terms not derived from a controlled subject heading system.
publisher keyword The name of the publisher. The publisher name is notoriously variable in bibliographic records. It is probably best to use a simple term like "wiley" instead of "John Wiley".
publisher-place keyword The place of publication.
isbn, issn, ismn standard number Fields for searching on ISBN, ISSN and ISMN. These fields are not in our Advanced Search form, instead it use the isn field below.
isn standard number This searches across various standard number fields, including ISBN, ISSN, and ISMN.
date numeric The year a work was published.
map-scale numeric The scale of a map.
keyword keyword Keyword terms searched across most fields in the records.
note keyword Searches notes in the records. This field isn't currently in the Advanced Search form.
document-type defined term Limits the results to the given document type. The only values that can be used for this field are: book, collection, graphic, periodical, map, mixed-material, music-recording, music-score, object, projected, sound-recording, & thesis.
document-format defined term Limits the results to the given format. The only values that can be used for this fields are: online, manuscript, microform, & print.
language defined term The terms for the language query need to be three letter language codes defined in the MARC21 Code List for Languages by the Library of Congress.
held-by defined term The terms for this field are the Institution codes we define for our contributing libraries. You can find a list on our Contributing Libraries page.
region defined term Limits the results to items held in the given region or regions. The only values that can be used for this field are: EM, EE, LON, NEE, NWE, SEE, SWE, WM, YAH, CS, SS, NS, NWA, MWA, SWA, NI, ROI.
Other fields available in the query string part of the url.
Field name Comments
format Set this to json to get the JSON response as shown above. If this is unset you will get an HTML response. However, the API does understand the HTTP Accept header and therefore you can use content negotiation to force a json response instead of using the format url parameter.
next-page This is used to get the next page of results when paging through a result set. The value should contain the token taken from the "next-page" value in the JSON response.
sort By default records are returned in a ranked order. You can change the order by using the sort field. Valid values are: title, -title, year, -year, & rank
The types of search term supported.
Type of field Comments
keyword Keyword fields support phrase searching, wildcards and boolean operations. For full details of what is supported see our search help.
numeric

Numeric fields support searching on a discrete or range of values. The following are all valid ranges that might be used for the date or map-scale field:

  • 1950-1960
  • 1700..1799
  • 2010-
  • ..1600
  • ~50000
  • ~1960

A tilde can prefix a single date or map scale and turns the term into a range query. For the date search it is the given year plus or minus 5 years. For other numeric fields it is the given number plus or minus 30%.

standard number Standard number fields are treated as keyword fields, though the default boolean operator is boolean-OR; hence multiple ISBNs can be given in a single query term to find multiple items.
defined term Defined term fields can contain multiple space separated terms and are combined as boolean-OR terms.