Manuscripts Online API

Manuscripts Online (http://www.manuscriptsonline.org/) enables you to search a diverse body of online primary resources relating to written and early printed culture in Britain during the period 1000 to 1500. The resources include literary manuscripts, historical documents and early printed books which are located on websites owned by libraries, archives, universities and publishers. The Manuscripts Online API enables users to connect programmatically to the search engine, using GET parameters, and retrieve search results in an XML format.

API Location

The Manuscripts Online API is available at https://www.hrionline.ac.uk/Manuscripts/search.jsp.

Input Parameters

At least one keyword, person or place name must be specified. Any number of parameters may be combined but, unless otherwise stated, each parameter can only have single value - see URL-encoded Strings for details on how to search for multiple values or phrases. Input parameters should be appended as parameters to the URL (e.g. https://www.hrionline.ac.uk/Manuscripts/search.jsp?rs=katherine&sr=bc,ci,te. Further examples of API queries can be found in Example API Queries).

Parameter codeParameterPermitted values
kwKeywordAny URL-encoded String. Details about the format of valid URL-encoded search strings can be found beneath the table.
kwvKeyword Name Variant One of the following, if this parameter is not specified, variants are not searched.
  • yes
  • no
pcPlace NameAny valid URL-encoded String.
pcvPlace Name Variant One of the following, if this parameter is not specified, variants are not searched.
  • yes
  • no
rsPerson NameAny valid URL-encoded String. The search will provide matches that contain at least one person name that matches all the criteria - i.e. a search for George* Clarence*, will search for any matches will contain a person name which contains both George and Clarence (in that order) and other characters in place of the wildcard. This field can also be used to search for people referred to by specific titles, e.g. Bishop of London, as well as given and family names.
rsvPerson Name Variant One of the following, if this parameter is not specified, variants are not searched.
  • yes
  • no
miReferenceAny URL-encoded String. Details about the format of valid URL-encoded search strings can be found beneath the table.
dtfCited Date FromAny date in the form yyyy or yyyy-mm-dd. Zero may be used (for example 1425-00-00 is equivalent to 1425 or 1425-03-00 may be used to search for March, 1425). The date search includes dates mentioned in the document as well as dates associated with the document. The date from should be equal to or less than the date to (if a date to is specified).
dttCited Date ToAny date in the form yyyy or yyyy-mm-dd. Zero may be used (for example 1425-00-00 is equivalent to 1425 or 1425-03-00 may be used to search for March, 1425). The date search includes dates mentioned in the document as well as dates associated with the document. The date to should be equal to or more than the date from (if a date from is specified).
sdfSource Date FromAny date in the form yyyy or yyyy-mm-dd. Zero may be used (for example 1425-00-00 is equivalent to 1425 or 1425-03-00 may be used to search for March, 1425). The date search includes dates mentioned in the document as well as dates associated with the document. The date from should be equal to or less than the date to (if a date to is specified).
sdtSource Date ToAny date in the form yyyy or yyyy-mm-dd. Zero may be used (for example 1425-00-00 is equivalent to 1425 or 1425-03-00 may be used to search for March, 1425). The date search includes dates mentioned in the document as well as dates associated with the document. The date to should be equal to or more than the date from (if a date from is specified).
srResourceTwo-letter code specifying the resource. More than one resource may be specified; each resource code should be separated by a comma (URL-encoded as %2c). If this parameter is not specified, all resources are searched. Valid codes are:-
  • am - The Auchinleck Manuscript
  • ct - The Norman Blake Editions of the Canterbury Tales
  • bh - British History Online
  • ci - British Library Catalogue of Illuminated Manuscripts
  • mo - British Literary Manuscripts Online, Medieval and Renaissance
  • bc - Cause Papers in the Diocesan Courts of the Archbishopric of York, 1300-1858
  • pv - The Corpus of Middle English Prose and Verse
  • tc - Early English Books Online - Text Creation Partnership
  • ei - Europa Inventa
  • go - Geographies of Orthodoxy: Mapping Pseudo-Bonaventuran Lives of Christ, 1350-1550
  • ih - Imagining History: Perspectives on late medieval vernacular historiography
  • ls - Late Medieval English Scribes
  • gm - Linguistic Geographies: The Gough Map of Great Britain
  • wm - Manuscripts of the West Midlands
  • md - Middle English Dictionary
  • mg - The Middle English Grammar Corpus (MEG-C)
  • te - Middle English Texts Series
  • na - The National Archives
  • pw - Parker on the Web
  • pu - Production and Use of English Manuscripts: 1060-1220
  • tx - The Taxatio
The order in which the resources are specified does not matter and does not affect the returned results.
ctCategoryA letter code. More than one category may be specified; each category code should be separated by a comma (URL-encoded as %2c). Some resources and / or results may match more than one category - for example, British History Online falls into both the "Literary Manuscripts" category and the "Official Documents (government, civic, legal, religious)" category.
  • a - all (default if not provided)
  • lm - Literary Manuscripts
  • nm - Non-literary Manuscripts
  • od - Official Documents (government, civic, legal, religious)
  • lb - Literary Printed Books
  • nb - Non-literary Printed Books
  • ma - Maps and Works of Art
ftFormatA single letter code. More than one format may be specified; each format code should be separated by a comma (URL-encoded as %2c).
  • a - all (default if not provided)
  • t - Full-text transcription
  • s - Summary or Calendar
  • m - Manuscript Description
acAccess TypeA single letter code
  • a - all (default if not provided)
  • f - Free / No Subscription
  • s - Subscription

URL-encoded Strings

Search strings may contain several words, separated by spaces (URL-encoded as +) - which will result in an OR search, matching texts that contain any of the words. An exact match may be carried out by enclosing a multi-word phrase in double quotes, or the user may specify that one or more of the words must be present by using a plus (URL-encoded as %2b) in front of the required word(s). Results containing certain words can be excluded by placing a minus sign(-) in front of the words. + and - can not be used to mandate or exclude words within exact phrases (i.e. within double quoted phrases) but can be used before phrases to indicate a required or excluded phrase.

* can be used as a wildcard in the middle or end of a word or phrase (e.g. ta*lor returns taylor and tailor), but not at the start; the more letters you specify the better.

XML Output

The results are returned as a UTF-8 encoded XML document with a root element, CHSP. The XML document consists of two main subsections - a Q element, which details the query submitted and a RES element which provides the results, and also facets which can be used to drill down through the results. Results are generally returned in channels, each channel representing a single collection / data source.

REFINE

The REFINE section contains details of search facets, each detailed with a PARAM element, that can be used to drill down into the results. Each result set can be drilled down via by document category ("ct"), document format ('ft'), date ("dt" ),and availability ("ac" - whether the source material is available to all users or only to those with a subscription). Each PARAM element has three attributes - name(ct, ft, dt or ac); value (a String description of the limits of the facet), and match (the number of documents that match this facet). As documents may match more than one facet description, the total number of matches may exceed the total number of results.

CHANNEL

The actual search results are contained in one or more channels. A single channel result is returned if:-

  • Fewer than 20 results are returned in total - a single, mixed channel is returned.
  • Results are only returned from one source collection, either because the query specified only one collection or only one collection contained matches.
Unless fewer than 20 results are returned, each channel relates to one specific source collection. The CHANNEL element has attributes sn (start index for results), en (end index for results), ip(items per page), m (total number of matches for this channel), type, sid (electronic resource id, equivalent to the sr codes for queries, or "nyi" if a mixed channel - further details on the sr codes can be found in the Input Parameters table). The channels are ordered by Lucene scores - the one with the highest scoring first result is returned first. This means that the channels have no fixed order.

Each channel has a channel name (CN) which either identifies it as a mixed channel or provides a brief textual description of the source collection. Each channel then consists of a number of R elements, each of which contains a single (numbered) result or match. Within the R Element, the T element provides the match title, one or more U elements the provides the URL (the link to the document in the source collection) ) with attribute CHOICE denoting the url as either default or a giving its source name, and the S element - a text snippet which usually contains some highlighted terms (within b tags) that match the search query. As many of the source collections require the user to have a subscription, the URL may display an error rather than direct the user to the source material if the user is not currently logged in, via a personal or institutional subscription.

Example API queries

Exclusion (John, not Marchaunt) - https://www.hrionline.ac.uk/Manuscripts/search.jsp?kw=%2bJohn+-Marchaunt
Exact phrase ("Richard of York") - https://www.hrionline.ac.uk/Manuscripts/search.jsp?kw=%22Richard+of+York%22
Specific Resources - https://www.hrionline.ac.uk/Manuscripts/search.jsp?rs=Katherine&sr=bc,ci,te
Wildcard - https://www.hrionline.ac.uk/Manuscripts/search.jsp?rs=Katherine*
Dates (years) - https://www.hrionline.ac.uk/Manuscripts/search.jsp?dtf=1325&dtt=1450&rs=John
A mixed channel - https://www.hrionline.ac.uk/Manuscripts/search.jsp?kw=coriander
An invalid request (generates error page) - https://www.hrionline.ac.uk/Manuscripts/search.jsp?kw=coriander&dtf=15-0000--00-00-00

Errors

Invalid use of codes or invalid data will usually result in the return of an empty result set, such as this. Where another error occurs, an error document is returned. Please contact us if you encounter unexpected errors.

Contact Us

The HRI developer currently responsible for maintaining the Manuscripts Online API is Katherine Rogers. 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/.

Cite this page:

"Api" Manuscripts Online (www.manuscriptsonline.org, version 1.0, 16 August 2018), https://www.manuscriptsonline.org/api