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.
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.dhi.ac.uk/Manuscripts/search.jsp?rs=katherine&sr=bc,ci,te. Further examples of API queries can be found in Example API Queries).
| Parameter code | Parameter | Permitted values |
|---|---|---|
| kw | Keyword | Any URL-encoded String. Details about the format of valid URL-encoded search strings can be found beneath the table. |
| kwv | Keyword Name Variant |
One of the following, if this parameter is not specified, variants are not searched.
|
| pc | Place Name | Any valid URL-encoded String. |
| pcv | Place Name Variant |
One of the following, if this parameter is not specified, variants are not searched.
|
| rs | Person Name | Any 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. |
| rsv | Person Name Variant |
One of the following, if this parameter is not specified, variants are not searched.
|
| mi | Reference | Any URL-encoded String. Details about the format of valid URL-encoded search strings can be found beneath the table. |
| dtf | Cited Date From | Any 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). |
| dtt | Cited Date To | Any 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). |
| sdf | Source Date From | Any 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). |
| sdt | Source Date To | Any 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). |
| sr | Resource | Two-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:-
|
| ct | Category | A 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.
|
| ft | Format | A single letter code. More than one format may be specified; each format code should be separated by a comma (URL-encoded as %2c).
|
| ac | Access Type | A single letter code
|
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.
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.
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.
The actual search results are contained in one or more channels. A single channel result is returned if:-
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.
Exclusion (John, not Marchaunt) - https://www.dhi.ac.uk/Manuscripts/search.jsp?kw=%2bJohn+-Marchaunt
Exact phrase ("Richard of York") - https://www.dhi.ac.uk/Manuscripts/search.jsp?kw=%22Richard+of+York%22
Specific Resources - https://www.dhi.ac.uk/Manuscripts/search.jsp?rs=Katherine&sr=bc,ci,te
Wildcard - https://www.dhi.ac.uk/Manuscripts/search.jsp?rs=Katherine*
Dates (years) - https://www.dhi.ac.uk/Manuscripts/search.jsp?dtf=1325&dtt=1450&rs=John
A mixed channel - https://www.dhi.ac.uk/Manuscripts/search.jsp?kw=coriander
An invalid request (generates error page) - https://www.dhi.ac.uk/Manuscripts/search.jsp?kw=coriander&dtf=15-0000--00-00-00