Child pages
  • Request a HOLLIS+ Search [Beta]
Skip to end of metadata
Go to start of metadata

With the retirement of the HOLLIS (AquaBrowser) discovery layer, we introduce a new search API against the HOLLIS+ (Primo) layer that returns bibliographic items in the same relevancy ranking order as the HOLLIS+ UI.

Individual bibliographic items will be returned in Dublin Core format, with some additional fields. Furthermore, you may additionally request faceting on a variety of axes.

URL request syntax

The base syntax, which performs a search against "everything" is:

http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?q={query_string}

 

There are several additional parameters that can be added

Parameters

Parameter

Value

Description

 

 

 

q

query_string

Your search values for an "everywhere" search. See Supported Primo API parameters for using Primo API parameters instead of using q .

jsonp

callback function name

The name of the callback function to wrap around JSON data.  Example: ?jsonp=ws_results

limit

an integer

The number of items you want returned (default is 30)

facets

a comma-delimited list of facets

all”, or one or more of the supported facet sets (see below). Specifying one or more facets will result in the display of facets across the entire results set.

 

Supported Primo API parameters.

They are described in fuller detail at ExLibris’s Developers’ Network Website: https://developers.exlibrisgroup.com/primo/apis/webservices/xservices/search/briefsearch . If you use one or more of these, you do not need to include the q parameter, above:

query

a query formatted in Primo API style

The format is <field>,<precision>,<value>; e.g.: creator,contains,leo+tolstoy or title,exact,war+and+peace

See the table below for some common valid values for <field> and <precision>.

query_inc

comma-delimited list of facet values specified against a particular facet set

Allows you to limit your search to those results matching the specified facet values for the specified facet set. The format is: facet_{facet set name},exact,{value1, value2,…}; e.g.: facet_rtype,exact,dissertations,journals gets only those results that are of resource type dissertation or journal.

query_exc

comma-delimited list of facet values specified against a particular facet set

Allows you to limit your search to those results that do not match the specified facet values for the specified facet set; e.g.:

facet_genre,exact,scores,historical+re-creations would exclude any results with the genre of “Score” or “Historical re-creation”

sortField

a sort value

One of:

1) stitle - performs Title sort. 
2) scdate - performs Date sort (reverse chronological order). 
3) screator - performs Author sort. 
4) popularity - Performs Popularity sort. 

If you do not specify the sortField, the results are ordered by relevance.

 

Commonly used Primo API fields

For use as <field> in Primo query syntax.

creator

The author of the work

title

Title of the work Note: a title search includes a search of the table of contents (MARC field 505); if you want to exclude those, use swstitle (“sort title”)

sub

Subject of the work

rtype

Resource type

cdate

Creation date (YYYY)

isbn

 

issn

 

lsr04

publisher

lsr05

place of publication

facet_tlevelValues are "available", "available_onsite", "online_resources", "peer_reviewed"
facet_pfilterResource type (type of material), such as "books", "newspaper_articles", "articles", "reviews"

lsr06

Fund(bookplate)

There are two useful values for the <precision> in the Primo query syntax:

contains

will return results for any item whose <field> contains at least one of the given terms

exact

will return results for any item whose <field> contains an exact match of the input term

Facet Sets

PRESTO currently supports faceting on several axes; for convenience, some of them are re-named from their Primo titles, which are provided in parentheses

FacetSet

Comments

Examples

creator

 

 

lang

language (MARC code)

“eng” or “ger”

lcc

Library of Congress basic class

“U - Military science.”

library

one of the Harvard libraries, preceded by “HVD_”

“HVD_LAM”, “HVD_DIV”

Note: “HVD_NET” refers to online resources

topic

(aka subject)

"Pacifism", "Military history, Ancient"

place (local31)

Geographic location associated with the bib. item

"Lebanon, New Hampshire, United States", "Italy"

 

genre

 

“Maps”, “Epic Fiction”

resource (rtype)

Resource Type

“archives_manuscripts”, “book”

avail (tlevel)

This can have two values only: “online_resources” and “available”. “Available” is the equivalent of “not checked out”

 

 

 

 

Sample URLs

A basic search using the q parameter is equivalent to entering search terms in the HOLLIS+ search box. Use quotation marks for exact string matches.

search for verba, sidney:

http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?q= %22verba,+sidney%22

If wanted your search to only contain results where verba, sidney is the creator, you would use the Primo syntax:

http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?query=creator,contains,verba++sidney

A combination title/author search for old man and the sea and hemingway, ernest 1899-1961:

http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?query=title,exact,%22old+man+and+the+sea%22&query=creator,contains,Hemingway++Ernest++1899-1961

Response

The response to a HOLLIS+ search may contain further links for moving to the next set of results, refining the search, etc., as described below. You can limit the number of results that are returned; experientially, the high limit seems to be about 200.

Any call to the PRESTO HOLLIS+ Search returns an XML document (or JSON version of it, if requested) with, minimally, the following elements.

Top level XML

For a HOLLIS search, the top level elements in the returned XML look like this:

<results>
  <totalResults>808</totalResults>
  <startIndex>1</startIndex>
  <itemsPerPage>30</itemsPerPage>
  <resultSet>
    <!—a set of individual <item/> records -->
  </resultSet>
  <pager><!-- page details here --></pager>
  <!—if you have requested faceting -->
  <facetSets>
    <facetSet><!—the faceting details for this Set -->
  </facetSets>
</results>

 

Note that if the number of results is fewer than the limit requested (default: 30), the <pager> element is not present.

Item  element details

The <resultSet><items> element  contains only <item> elements. The <item> element has two attributes:

  • id The HOLLIS+ ID

  • position (in the list of results)

  • rank (NEW) The calculation of ranking for this item within the search results.

The <item> will also enclose many of the elements listed below, as they are available:

  • dc:title

  • cataloglink -- the URL pointing to the Permanent URI of the item

  • dc:type (book, archive_manuscript, image, etc.)

  • dc:creator (multiple) – the author(s), if known

  • dc:contributor (multiple) any additional known contributors to the work

  • authorlink – the query string needed to search for all items created by the dc:creator

  • dc:subject (multiple)

  • dc:description (multiple)

  • dc:date – a text field, usually a year.

  • dc:publisher

  • notes – any public notes associated with the bibliographic item

  • dc:identifier (multiple) -- the OCLC, ISBN, ISSN number(s) as they are available

  • (Images) numberofimages

  • (Images) related – text description of what the item is related to

  • (Images) restrictions – text restrictions

  • (Images) links (multiple) – represented as <a href> elements, links to thumbnail and copyright and permissions

<pages> element details

If there are more results than requested by the limit parameter (default: 30), the <pager> element will be present, and contain sub elements. Here's an example from a results XML with 29 results when the requested limit was 20:

The request URL for the example was:

http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?query=sub,contains,seven+wise+men+of+greece&limit=20

<pages>
  <currentpage>1</currentpage>
  <page querystr="?query=sub,contains,seven+wise+men+of+greece&amp;limit=20&amp;curpage=2">Next</page>
  <page querystr="?query=sub,contains,seven+wise+men+of+greece&amp;limit=20&amp;curpage=2">Last</page>
</pages>

Note the querystr attribute of the <page> element; this string would be used to get the results for whichever “page” was next requested. For the case above, to obtain the last item that fulfills the search, the URL would be:

http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?query=sub,contains,seven+wise+men+of+greece&limit=20&curpage=2

<facetSets> element details

The <facetSets> element will only be present if you have requested faceting as described above.

The <facetSets> will enclose one or more <facetSet> elements, depending on which facets you have requested.

The <facetSet> element will look as follows:
(the URL was: http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?query=sub,contains,seven+wise+men+of+greece&limit=20&facets=creator)

<facetSetType>creator</facetSetType>
<facetsCount>25</facetsCount>
<facet>
<title>Erasmus, Desiderius, -1536</title>
<count>4</count>
<link>?query=sub,contains,seven+wise+men+of+greece&amp;limit=20&amp;curpage=1&amp;query=facet_creator,exact,Erasmus++Desiderius++-1536</link>
</facet>
<facet>
<title>Snell, Bruno, 1896-</title>
<count>3</count>
<link>?query=sub,contains,seven+wise+men+of+greece&amp;limit=20&amp;curpage=1&amp;query=facet_creator,exact,Snell++Bruno++1896-</link>
</facet>
.
.
.
</facetSet>

 

The <link>, if appended to "http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/", will produce a set of results refined by the facet.  So if you took the creator facet for title = Erasmus, Desiderius, -1536 , and used the link, you would form the url:http://webservices.lib.harvard.edu/rest/v2/hollisplus/search/dc/?query=sub,contains,seven+wise+men+of+greece&amp;limit=20&amp;curpage=1&amp;query=facet_creator,exact,Erasmus++Desiderius++-1536

 

At this time, the ordering of the <facet> elements within the <facetSet> is by item count, descending.

  • No labels