Search API

Overview

The Summon Search API is a service that exposes all of the search capabilities of Summon. The API is an HTTP-based service and supports requests via the HTTP GET and POST methods. Currently there are two available response formats: XML and JSON. All requests to the API require authentication via private-key digest. The API receives requests and returns responses encoded in UTF-8. The data that can be retrieved from the Search API include meta documents, facet counts and spelling suggestions.

In addition to the traditional parameter-based query system, the Search API includes a new command-based query system that can be used standalone, or in conjunction with parameters. Commands provide some unique benefits over raw parameters, since they can provide additional information to the API about the action being performed. When the API knows about actions being performed by the client it can execute common search logic, such as paging and did you mean, on the client's behalf. This can greatly simplify the ease and speed of client implementation. For more specific information on the command system, see Commands.

There are four parts to making a Search API request:

  1. Build the URL query string;
  2. Build the HTTP request headers;
  3. Build an authentication digest based on the query string and headers; and
  4. Parse the response and handle any errors.

Query String

Queries are comprised of parameters, commands and tokens, and follow the standard URL format (key=value&anotherKey=otherValue). All queries must be properly URL encoded using UTF-8 character encoding. Query parameter values, and command argument values, contain special characters that will need to be escaped before URL encoding. Some parameters, such as the text query parameter, accept Lucene-specific query syntax, which will need to be escaped as well.

Characters may be escaped with the backslash ('\') character. For all parameter values, and command arguments except s.q and s.fq, the characters that must be escaped include: ,:\()${}. For parameters and arguments that hold Lucene query syntax, characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Lucene special characters only need to be escaped if their special meaning was not intended. If Lucene escaping and regular escaping are both needed, as in the setTextQuery() command, the Lucene escaping must be performed before regular escaping.

Example - Constructing a query URL

Query for:

  Probability models of recidivism: an exploration

Filter by:

  Author: Linster, Richard L

Text Query:

  Probability models of recidivism\: an exploration

  Note that ':' is escaped in a Lucene query, but no other escaping is needed for the s.q parameter

Text Filter:

  Author:(Linster, Richard L)

Add Text Filter Command After Escaping:

  addTextFilter(Author\:\(Linster\, Richard L\))

  Note that ':', ',', '(' and ')' are escaped

URL query string before encoding:

  s.q=Probability models of recidivism\: an exploration&s.cmd=addTextFilter(Author\:\(Linster\, Richard L\))

URL query string encoded:

  s.q=Probability+models+of+recidivism%5C%3A+an+exploration&s.cmd=addTextFilter%28Author%5C%3A%5C%28Linster%5C%2C+Richard+L%5C%29%29

Try It

For more specific information on building the URL query string, see: Parameters, Commands and Tokens.


Request Headers

The Search API uses five request headers:

The Accept header is used to tell the API which response type to return. Currently supported values are application/xml and application/json. This header is included when building the authentication digest.

The x-summon-date header is used during the authentication process, and is checked against the timestamp on the server. The date value is in standard Date format as defined in RFC 2616. This header is included when building the authentication digest.

The Host header is a required HTTP header and is used internally to service the request. It follows the standard format for the HTTP Host header, as defined in RFC 2616. This header is included when building the authentication digest.

The Authorization header is used for both authentication and authorization. The header contains an access ID and a digest of specific request attributes computed with a secret key corresponding to the access ID. The server authenticates a request by comparing the digest from the Authorization header with a server-computed digest.

The x-summon-session-id header is an optional header that is used to link user sessions to API sessions. The session ID is returned in the response, and if this header is not present, a session ID will be generated for the request. If the x-summon-session-id is not sent with the first API request, then the generated session ID from the response should be sent in the x-summon-session-id header on all subsequent requests.

Example - Search API request headers

               Host: api.summon.serialssolutions.com
             Accept: application/xml
      x-summon-date: Mon, 29 Jun 2009 23:07:20 GMT
      Authorization: Summon test;TUDe5VCP520njOGCP8bg3uKR6OM=
x-summon-session-id: 0iy5u3VAkySQ3/Nbd7TT+WKdEYk=

Authentication Digest

Authentication digests are HMAC-SHA1, Base64-encoded strings. They are computed from various request elements using a secret key. Computed digests are time sensitive, and will expire once their computed time is too different from the server time. For specific details on building the authentication digest, see Authentication.


Response

All responses from the Search API are UTF-8 encoded. There are currently two response formats supported: custom JSON and custom XML. The HTTP Accept header determines which response type is returned.

Two conditions may occur before a request is processed that will cause no response to be returned:

If the API is capable of handling the request, and authentication passes, a response object is returned in either XML or JSON. The response object contains the results of the query, as well as metadata about the query that can be used either for display purposes or for further refinement of the query. The response may also contain more descriptive errors than the HTTP status errors. For more information on the response, see Response and Errors.






Commands

Overview

Commands are similar to parameters and provide access to all the same functionality that the parameters do, but they have some distinct advantages. Commands give the Search API one piece of information that direct parameters do not: the action being performed. When the API receives a request via parameters only, all it can do is interpret that request directly. The API must assume that the client has applied all search logic -- such as paging, did you mean (DYM), and facet paging -- correctly. When the API receives a request via a command, it has the information it needs to make some intelligent decisions about search logic.

Commands allow the Search API to provide uniform search logic to all clients across different platforms and implementations, without needing to distribute any client code. Using commands reduces client-side search logic and URL-manipulation code. This makes it easier to learn how to use the API, and keeps developers thinking about the business logic specific to their application rather than the internal implementation details of search logic. Commands are also more efficient because the server needs to parse and interpret the query string when it executes a search. This is a perfect time to apply search logic directly to the search, and doesn't require any additional parsing or assembly steps. If search logic is performed on the client side instead, then the client needs to perform the extra steps of parsing the query, applying logic and re-assembling a new query, before it is sent to the API.

Because commands are not guaranteed to be received by the API in any specific order, a natural order is applied to commands. Commands will always be executed in the order they appear in the Quick Reference list.

For more details on specific commands, see the Topics list on the left, and the Quick Reference list.


A Use Case

Assume that an end user does a search via two search terms, author and title. DYM is enabled on the original search, and there are several facet fields specified. When the user receives their results, they page through several facet-value options, click through to page two (for which the client simply sends a new request with s.pn=2, and forgets to disable DYM). Then the client clicks on a facet value to be applied as a filter.

At this point, the correct search logic would be to disable DYM, set page number to one, set all facet-field page numbers to one, and add the facet-value filter. A naive client implementation may simply append one new s.fvf parameter to the existing query string, and send that as the new query. This would appear wrong to the end user, since the result set would completely change, and they would not be directly entering anything that would need spelling correction, yet they could end up on page two of the result set, with spelling corrections coming back, drilled down to pages of facet fields that don't provide any limiting values for the current query.

If the client appended s.cmd=addFacetValueFilter(...) to the existing query instead of appending an s.fvf parameter directly, the API would have detected what the client was doing and applied all of the above-mentioned search logic automatically. The results would make sense to the end user, and the client wouldn't have to do any additional URL manipulation.

Characters may be escaped with the backslash ('\') character. For all command arguments, the following characters must be escaped: ,:\()${}.

Some special characters may need to be escaped for command arguments that hold Lucene-style query syntax. Characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Lucene special characters only need to be escaped if their special meaning was not intended. If Lucene escaping is needed it must be performed before regular argument escaping.

Example - Building queries via commands

Start with a blank query and ask for ContentType facet field:

  Append:

    s.cmd=addFacetField(ContentType,or,1,10)

  Which becomes:

    s.ff=ContentType%2Cor%2C1%2C10

Search for documents with author of Jonathan Swift and title of Gulliver's Travels:

  Append:

    s.cmd=addTextQuery(Author\:\(Jonathan+Swift\))+addTextQuery(Title\:\(Gulliver's+Travels\))

  To make:

    s.ff=ContentType%2Cor%2C1%2C10&s.cmd=addTextQuery(Author\:\(Jonathan+Swift\))+addTextQuery(Title\:\(Gulliver's+Travels\))

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10

Move to next page:

  Append:

    s.cmd=nextPage()

  To make:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.cmd=nextPage()

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.pn=2

Move to next facet-field page:

  Append:

    s.cmd=nextFacetPage(ContentType)

  To make:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.pn=2&s.cmd=nextFacetPage(ContentType)

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C2%2C10&s.pn=2

Apply ContentType facet-value filter of "Book":

  Append:

    s.cmd=addFacetValueFilter(ContentType,Book)

  To make:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C2%2C10&s.pn=2&s.cmd=addFacetValueFilter(ContentType,Book)

  Which becomes:

    s.q=Title%3A%28Gulliver%27s+Travels%29&s.q=Author%3A%28Jonathan+Swift%29&s.ff=ContentType%2Cor%2C1%2C10&s.fvf=ContentType%2CBook%2C

Notice that s.pn is removed, resetting the paging, and the ContentType facet field has been reset to page 1.

Try It





Facet Field Commands

Add Facet Field Command

Syntax

The syntax for the add facet field command is:

addFacetField(<facetField>, <combineMode>[, <pageNumber or whiteList>, <pageSize>])

The default value for pageNumber is 1, if unspecified. The default value for pageSize is 10, if unspecified.

A whiteList has the form value1:value2:.... It specifies a set of values that are to be included in the facet counts even if their counts are not in the top pageSize, provided only that their counts are non-zero.

Function

The add facet field command adds the facet field, and then it calls clearAllFacetPaging().

Example - Using the add facet field command

This add facet field command adds a new facet field for SubjectTerms and it resets paging on the ContentType facet field:

  s.ff=ContentType,or,2,15&s.cmd=addFacetField(SubjectTerms,and)

Try It


Example - Using the add facet field command with a white list

This command adds a new facet field for SubjectTerms and specifies that 5 values should be returned, including "education" provided that its count is non-zero:

  s.cmd=addFacetField(SubjectTerms,and,education,5)

Try It


Add Range Facet Field Command

Syntax

The syntax for the add range facet field command is:

addRangeFacetField(<facetField>, <minValue>:<maxValue>[:<inclusive>][, <minValue>:<maxValue>[:<inclusive>]]*)

The default value for inclusive is true, if unspecified.


Function

The add range facet field command adds the range facet field, and then it calls clearAllFacetPaging().

Example - Using the add range facet field command

This add range facet field command adds a new range facet field for several ranges in the PublicationDate field,
and it resets paging on the ContentType facet field:

  s.pn=3&s.ff=ContentType,or,2,15&s.cmd=addRangeFacetField(PublicationDate,1971:1980,1981:1990,1991:2000,2001:2010)

Try It


Clear All Facet Fields Command

Syntax

The syntax for the clear all facet fields command is:

clearAllFacetFields()

This command takes no arguments.


Function

The clear all facet fields command removes all facet fields from the request.

Example - Using the clear all facet fields command

This clear all facet fields command removes facet fields and leaves everything else in the query:

  s.pn=3&s.ps=10&s.q=bullfrog&s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and&s.cmd=clearAllFacetFields()

Try It


List Facet Values Command

Syntax

The syntax for the list facet values command is:

listFacetValues(<facetField>, <combineMode>)

There are no defaults for the listFacetValues command.


Function

The list facet values command adds the facet field, and then it calls clearAllFacetFields() setPageSize(0) setHighlighting(false) addFacetField(<facetField>, <combineMode>, 1, 100).

Example - Using the list facet values command

This list facet values command lists facet values for SubjectTerms:

  s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and,1,10&s.cmd=listFacetValues(SubjectTerms,and)

Try It


Remove Facet Field Command

Syntax

The syntax for the remove facet field command is:

removeFacetField(<facetField>)

There are no defaults for the removeFacetField command.


Function

The remove facet field command removes the indicated facet field, and then it calls clearAllFacetPaging().

Example - Using the remove facet field command

This remove facet field command removes the facet field for SubjectTerms and it resets paging on the ContentType facet field:

  s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and&s.cmd=removeFacetField(SubjectTerms)

Try It


Facet Value Filter Commands

Add Facet Value Filters Command

Syntax

The syntax for the add facet value filters command is:

addFacetValueFilters(<facetField>, <value>[: <negated>][, <value>[: <negated>]]*)

The default value for negated is false, if unspecified.


Function

The add facet value filters command adds the facet value filters, and then it calls clearAllPaging().

Example - Using the add facet value filters command

This add facet value filters command adds a new facet value filter ContentType Book,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.cmd=addFacetValueFilters(ContentType,Book:false)

Try It


Add Facet Value Group Filter Command

Syntax

The syntax for the add facet value group filter command is:

addFacetValueGroupFilter(<facetField>, <combineMode>, <value>[, <value>]*)

There are no defaults for the addFacetValueGroupFilter command.


Function

The add facet value group filter command adds the facet value group filter, and then it calls clearAllPaging().

Example - Using the add facet value group filter command

This add facet value group filter command adds a new facet value group filter for education or literature,
and it resets paging on the SubjectTerms facet field and page number:

  s.pn=3&s.ff=SubjectTerms,and,2,15&s.cmd=addFacetValueGroupFilter(SubjectTerms,or,education,literature)

Try It


Clear All Facet Value Filters Command

Syntax

The syntax for the clear all facet value filters command is:

clearAllFacetValueFilters()

This command takes no arguments.


Function

The clear all facet value filters command removes all facet value filters from the request, and then it calls clearAllPaging().

Example - Using the clear all facet value filters command

This clear all facet value filters command removes facet value filters, resets paging, and leaves everything else in the query:

  s.pn=3&s.ps=10&s.q=surgery&s.fvf=ContentType,Book&s.fvf=SubjectTerms,north+america&s.cmd=clearAllFacetValueFilters()

Try It


Negate Facet Value Filter Command

Syntax

The syntax for the negate facet value filter command is:

negateFacetValueFilter(<facetField>[, <value>])

The default value for value is all values, if unspecified.


Function

The negate facet value filter command negates the facet value filter specified if a value is present. If no value is present and only a facet field is given then all facet value filters for that facet field will be negated. After negating facet value filters, this command calls clearAllPaging().

Example - Using the add facet value filter command

This negate facet value filter command negates all ContentType facet value filters,
and negates the north america SubjectTerms facet value filter,
and it resets paging on the facet fields and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and,2,15&s.fvf=ContentType,Book
  &s.fvf=ContentType,Journal+Article&s.fvf=SubjectTerms,north+america&s.fvf=SubjectTerms,u.s
  &s.cmd=negateFacetValueFilter(ContentType)+negateFacetValueFilter(SubjectTerms,north+america)

Try It


Remove Facet Value Filter Command

Syntax

The syntax for the remove facet value filter command is:

removeFacetValueFilter(<facetField>[, <value>])

The default value for value is all values, if unspecified.


Function

The remove facet value filter command removes the facet value filter specified if a value is present. If no value is present and only a facet field is given then all facet value filters for that facet field will be removed. After removing facet value filters, this command calls clearAllPaging().

Example - Using the remove facet value filter command

This remove facet value filter command removes all ContentType facet value filters,
and removes the north america SubjectTerms facet value filter,
and it resets paging on the facet fields and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and,2,15&s.fvf=ContentType,Book
  &s.fvf=ContentType,Journal+Article&s.fvf=SubjectTerms,north+america&s.fvf=SubjectTerms,u.s
  &s.cmd=removeFacetValueFilter(ContentType)+removeFacetValueFilter(SubjectTerms,north+america)

Try It


Remove Facet Value Group Filter Command

Syntax

The syntax for the remove facet value group filter command is:

removeFacetValueGroupFilter(<id>[, <value>])

The default value for value is all values, if unspecified.


Function

The remove facet value group filter command removes the value specified if a value is present. If no value is present and only an id is given then the entire facet value group filter will be removed. After removing specified value or group filter, this command calls clearAllPaging().

Example - Using the remove facet value group filter command

This remove facet value group filter command removes entire facet value group filter 1,
and removes the north america value from facet value grou pfilter 2,
and it resets paging on the facet fields and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and,2,15&s.fvgf:1=ContentType,or,Book,Journal
  &s.fvgf:2=SubjectTerms,or,north+america,u.s
  &s.cmd=removeFacetValueGroupFilter(1)+removeFacetValueGroupFilter(2,north+america)

Try It


Set Facet Value Filters Command

Syntax

The syntax for the set facet value filters command is:

setFacetValueFilters(<facetField>, <value>[: <negated>][, <value>[: <negated>]]*)

The default value for negated is false, if unspecified.


Function

The set facet value filters command adds the facet value filters, replacing any existing facet value filters, and then it calls clearAllPaging().

Example - Using the set facet value filters command

This set facet value filters command adds a new facet value filter ContentType Book,
and it removes the existing facet value filter SubjectTerms north america,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.fvf=SubjectTerms,north+america&s.cmd=setFacetValueFilters(ContentType,Book:false)

Try It


Global Commands

Clear All Command

Syntax

The syntax for the clear all command is:

clearAll()

This command takes no arguments.


Function

The clear all command blanks the query.

Example - Using the clear all command

This clear all command removes everything in the query:

  s.pn=3&s.ps=10&s.q=civil&s.fvf=ContentType,Book&s.fq=law&s.cmd=clearAll()

Try It


Clear Search Command

Syntax

The syntax for the clear search command is:

clearSearch()

This command takes no arguments.


Function

The clear search command calls clearAllTextQueries() clearAllSearchTerms() clearAllTextFilters() clearAllRangeFilters() clearAllFacetValueFilters() clearAllPaging(), resetting the search, but leaving all other parameters like params, page size and facet fields intact.

Example - Using the clear search command

This clear search command clears all search elements but leaves params page size and facet fields intact:

  s.pn=3&s.ho=true&s.ps=10&s.q=foreign&s.ff=ContentType,Book&s.fvf=ContentType,Book&s.fq=trade+economy&s.cmd=clearSearch()

Try It


Set Debugging Command

Syntax

The syntax for the set debugging command is:

setDebugging(<boolean>)

There are no defaults for the setDebugging command.


Function

The set debugging command enables or disables debugging mode.

Example - Using the set debugging command

This set debugging command enables debugging:

  s.cmd=setDebugging(true)

Try It


Set Did You Mean Command

Syntax

The syntax for the set did you mean command is:

setDidYouMean(<boolean>)

There are no defaults for the setDidYouMean command.


Function

The set did you mean command can be used to override the default for whether did you mean suggestions are enabled or not.

Example - Using the set did you mean command

This set did you mean command disables did you mean:

  s.q=calculus&s.cmd=setDidYouMean(false)

Try It


Set Highlight Delimiters Command

Syntax

The syntax for the set highlight delimiters command is:

setHighlightDelimiters(<startValue>, <endValue>)

There are no defaults for the setHighlightDelimiters command.


Function

The set highlight delimiters command sets the start and end highlight delimiters for highlighting in the response document fields.

Example - Using the set highlight delimiters command

This set highlight delimiters command sets the start highlight delimiter to <b> and the end highlight delimiter to </b>:

  s.pn=3&s.ff=ContentType,or,2,15&s.q=philosophy&s.cmd=setHighlightDelimiters(<b>,</b>)

Try It


Set Highlighting Command

Syntax

The syntax for the set highlighting command is:

setHighlighting(<boolean>)

There are no defaults for the setHighlighting command.


Function

The set highlighting command enables or disables highlighting in the response document fields.

Example - Using the set highlighting command

This set highlighting command disables highlighting:

  s.pn=3&s.ff=ContentType,or,2,15&s.q=art+history&s.cmd=setHighlighting(false)

Try It


Set Holdings Only Command

Syntax

The syntax for the set holdings only command is:

setHoldingsOnly(<boolean>)

There are no defaults for the setHoldingsOnly command.


Function

The set holdings only command enables or disables holdings only mode, and then it calls clearAllPaging().

Example - Using the set holdings only command

This set holdings only command enables holdings only,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.q=art+history&s.cmd=setHoldingsOnly(true)

Try It


ID Query Commands

Set Fetch IDs

Syntax

The syntax for the set fetch ids command is:

setFetchIDs(<FETCH_ID>,<FETCH_ID>,<FETCH_ID>)

Note: No more than 100 records can be added per query.


Function

The set fetch ids command is to be used when needing to retrieve one or many records by ID.

Paging Commands

Clear All Facet Paging Command

Syntax

The syntax for the clear all facet paging command is:

clearAllFacetPaging()

This command takes no arguments.


Function

The clear all facet paging command sets all facet field page numbers to 1.

Example - Using the clear all facet paging command

This clear all facet paging command sets facet field page numbers to 1:

  s.pn=3&s.ps=10&s.q=treefrog&s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and,3,20&s.cmd=clearAllFacetPaging()

Try It


Clear All Paging Command

Syntax

The syntax for the clear all paging command is:

clearAllPaging()

This command takes no arguments.


Function

The clear all paging command sets the page number to 1, and then it calls clearAllFacetPaging()

Example - Using the clear all paging command

This clear all paging command sets the page number to 1 and all facet field page numbers to 1:

  s.pn=3&s.ps=10&s.q=mathematics&s.ff=ContentType,or,2,15&s.ff=SubjectTerms,and,3,20&s.cmd=clearAllPaging()

Try It


Go To Facet Page Command

Syntax

The syntax for the go to facet page command is:

goToFacetPage(<facetField>, <pageNumber>)

There are no defaults for the goToFacetPage command.


Function

The go to facet page command sets the page number for a given facet.

Example - Using the go to facet page command

This go to facet page command sends the SubjectTerms facet field to page 3:

  s.ff=SubjectTerms,and,1,15&s.cmd=goToFacetPage(SubjectTerms,3)

Try It


Go To Page Command

Syntax

The syntax for the go to page command is:

goToPage(<pageNumber>)

There are no defaults for the goToPage command.


Function

The go to page command sets the page number, and then it calls clearAllFacetPaging().

Example - Using the go to page command

This go to page command sets the page number to 2 and all facet field page numbers to 1:

  s.pn=4&s.ff=SubjectTerms,and,3,15&s.cmd=goToPage(2)

Try It


Move Facet Page Command

Syntax

The syntax for the move facet page command is:

moveFacetPage(<facetField>, <pageDelta>)

There are no defaults for the moveFacetPage command.


Function

The move facet page command calls goToFacetPage(<facetField>, facetField.pageNumber + <pageDelta>).

Example - Using the move facet page command

This move facet page command changes the SubjectTerms facet field page number to 5:

  s.ff=SubjectTerms,and,2,15&s.cmd=moveFacetPage(SubjectTerms,3)

Try It


Move Page Command

Syntax

The syntax for the move page command is:

movePage(<pageDelta>)

There are no defaults for the movePage command.


Function

The move page command calls goToPage(query.pageNumber + <pageDelta>).

Example - Using the move page command

This move page command changes the page number to 5 and sets all facet field page numbers to 1:

  s.pn=7&s.ff=SubjectTerms,and,2,15&s.cmd=movePage(-2)

Try It


Next Facet Page Command

Syntax

The syntax for the next facet page command is:

nextFacetPage(<facetField>)

There are no defaults for the nextFacetPage command.


Function

The next facet page command calls moveFacetPage(1).

Example - Using the next facet page command

This next facet page command changes the SubjectTerms facet field page number to 6:

  s.ff=SubjectTerms,and,5,15&s.cmd=nextFacetPage(SubjectTerms)

Try It


Next Page Command

Syntax

The syntax for the next page command is:

nextPage()

This command takes no arguments.


Function

The next page command calls movePage(1).

Example - Using the next page command

This next page command changes the page number to 8 and sets all facet field page numbers to 1:

  s.pn=7&s.ff=SubjectTerms,and,2,15&s.cmd=nextPage()

Try It


Previous Facet Page Command

Syntax

The syntax for the previous facet page command is:

previousFacetPage(<facetField>)

There are no defaults for the previousFacetPage command.


Function

The previous facet page command calls moveFacetPage(-1).

Example - Using the previous facet page command

This previous facet page command changes the SubjectTerms facet field page number to 4:

  s.ff=SubjectTerms,and,5,15&s.cmd=previousFacetPage(SubjectTerms)

Try It


Previous Page Command

Syntax

The syntax for the previous page command is:

previousPage()

This command takes no arguments.


Function

The previous page command calls movePage(-1).

Example - Using the previous page command

This previous page command changes the page number to 6 and sets all facet field page numbers to 1:

  s.pn=7&s.ff=SubjectTerms,and,2,15&s.cmd=previousPage()

Try It


Remove Facet Paging Command

Syntax

The syntax for the remove facet paging command is:

removeFacetPaging(<facetField>)

There are no defaults for the removeFacetPaging command.


Function

The remove facet paging command sets the page number to 1 for the given facet.

Example - Using the remove facet paging command

This remove facet paging command sets the SubjectTerms facet field page number to 1:

  s.ff=SubjectTerms,and,2,15&s.cmd=removeFacetPaging(SubjectTerms)

Try It


Set Facet Page Size Command

Syntax

The syntax for the set facet page size command is:

setFacetPageSize(<facetField>, <pageSize>)

There are no defaults for the setFacetPageSize command.


Function

The set facet page size command sets the page size for the given facet, and then it calls removeFacetPaging(<facetField>).

Example - Using the set facet page size command

This set facet page size command changes the SubjectTerms facet field page size to 5,
and sets SubjectTerms page number to 1:

  s.ff=SubjectTerms,and,2,15&s.cmd=setFacetPageSize(SubjectTerms,5)

Try It


Set Page Size Command

Syntax

The syntax for the set page size command is:

setPageSize(<pageSize>)

There are no defaults for the setPageSize command.


Function

The set page size command sets the page size, and then it calls clearAllPaging().

Example - Using the set page size command

This set page size command changes the page size to 4,
and it resets paging on the facet fields and page number:

  s.pn=5&s.ff=SubjectTerms,and,2,15&s.cmd=setPageSize(4)

Try It


Range Filter Commands

Add Range Filter Command

Syntax

The syntax for the add range filter command is:

addRangeFilter(<fieldName>, <minValue>:<maxValue>[:<inclusive>])

The default value for inclusive is true, if unspecified.


Function

The add range filter command adds the range filter, and then it calls clearAllPaging().

Example - Using the add range filter command

This add range filter command adds a new range filter for PublicationDate,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.cmd=addRangeFilter(PublicationDate,1971:1980)

Try It


Clear All Range Filters Command

Syntax

The syntax for the clear all range filters command is:

clearAllRangeFilters()

This command takes no arguments.


Function

The clear all range filters command removes all range filters from the request, and then it calls clearAllPaging().

Example - Using the clear all range filters command

This clear all range filters command removes range filters, resets paging, and leaves everything else in the query:

  s.pn=3&s.ps=10&s.q=geography&s.fvf=ContentType,Book&s.rf=PublicationDate,1971:1980&s.cmd=clearAllRangeFilters()

Try It


Remove Range Filter Command

Syntax

The syntax for the remove range filter command is:

removeRangeFilter(<fieldName>[, <minValue>:<maxValue>[:<inclusive>]])

The default value for the range is all ranges, if unspecified.


Function

The remove range filter command removes the range filter specified if a field name and range are present. If no range is present and only a field name is given then all range filters for that field will be removed. After removing range filters, this command calls clearAllPaging().

Example - Using the remove range filter command

This remove range filter removes the 1991 to 2000 range filter,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.rf=PublicationDate,1991:2000&s.cmd=removeRangeFilter(PublicationDate,1991:2000)

Try It


Set Range Filter Command

Syntax

The syntax for the set range filter command is:

setRangeFilter(<fieldName>, <minValue>:<maxValue>[:<inclusive>])

The default value for inclusive is true, if unspecified.


Function

The set range filter command adds the range filter, replacing any existing range filters, and then it calls clearAllPaging().

Example - Using the set range filter command

This set range filter command adds a new range filter for PublicationDate,
and removes the old range filter for PublicationDate,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.rf=PublicationDate,1991:2000&s.cmd=setRangeFilter(PublicationDate,1971:1980)

Try It


Sort Commands

Reverse Sort Order Command

Syntax

The syntax for the reverse sort order command is:

reverseSortOrder()

This command takes no arguments.


Function

The reverse sort order command reverses the sort order, and then it calls clearAllPaging().

Example - Using the reverse sort order command

This reverse sort order command reverses the sort order,
and it resets paging on the facet fields and page number:

  s.pn=3&s.ps=10&s.ff=ContentType,or,3,15&s.sort=PublicationDate:asc&s.cmd=reverseSortOrder()

Try It


Set Sort By Relevancy Command

Syntax

The syntax for the set sort by relevancy command is:

setSortByRelevancy()

This command takes no arguments.


Function

The set sort by relevancy command removes the sort order, and then it calls clearAllPaging().

Example - Using the set sort by relevancy command

This set sort by relevancy command removes the sort order,
and it resets paging on the facet fields and page number:

  s.pn=3&s.ps=10&s.ff=ContentType,or,3,15&s.sort=PublicationDate:desc&s.cmd=setSortByRelevancy()

Try It


Set Sort Command

Syntax

The syntax for the set sort command is:

setSort(<fieldName>:<sortOrder>[, <fieldName>:<sortOrder>]*)

There are no defaults for the setSort command.


Function

The set sort command sets the sort order for the results, and then it calls clearAllPaging().

Example - Using the set sort command

  This set sort command sets the sort order to author ascending,
  and removes the sort order of date descending,
  and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.sort=PublicationDate:desc&s.cmd=setSort(PublicationDate:asc)

Try It


Text Filter Commands

Add Text Filter Command

Syntax

The syntax for the add text filter command is:

addTextFilter(<filterQuery>)

There are no defaults for the addTextFilter command. Lucene escaping applies to this command. Characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Special characters only need to be escaped if their special meaning was not intended. Regular argument escaping must be applied after Lucene escaping.


Function

The add text filter command adds the text filter, and then it calls clearAllPaging().

Example - Using the add text filter command

This add text filter command adds a new text filter for zoology,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.cmd=addTextFilter(zoology)

Try It


Clear All Text Filters Command

Syntax

The syntax for the clear all text filters command is:

clearAllTextFilters()

This command takes no arguments.


Function

The clear all text filters command removes all text filters from the request, and then it calls clearAllPaging().

Example - Using the clear all text filters command

This clear all text filters command removes text filters, resets paging, and leaves everything else in the query:

  s.pn=3&s.ps=10&s.q=policy&s.fvf=ContentType,Book&s.fq=trade+economy&s.cmd=clearAllTextFilters()

Try It


Remove Text Filter Command

Syntax

The syntax for the remove text filter command is:

removeTextFilter(<filterQuery>)

There are no defaults for the removeTextFilter command.


Function

The remove text filter command removes the text filter, and then it calls clearAllPaging().

Example - Using the remove text filter command

This remove text filter command removes the text filter for zoology,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.fq=zoology&s.cmd=removeTextFilter(zoology)

Try It


Set Text Filter Command

Syntax

The syntax for the set text filter command is:

setTextFilter(<filterQuery>)

There are no defaults for the setTextFilter command. Lucene escaping applies to this command. Characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Special characters only need to be escaped if their special meaning was not intended. Regular argument escaping must be applied after Lucene escaping.

Function

The set text filter command adds the text filter, replacing any existing text filters, and then it calls clearAllPaging().

Example - Using the set text filter command

This set text filter command adds a new text filter for zoology,
and removes the text filter for anthropology,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.fq=anthropology&s.cmd=setTextFilter(zoology)

Try It


Text Query Commands

Add Text Query Command

Syntax

The syntax for the add text query command is:

addTextQuery(<textQuery>)

There are no defaults for the addTextQuery command. Lucene escaping applies to this command. Characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Special characters only need to be escaped if their special meaning was not intended. Regular argument escaping must be applied after Lucene escaping.


Function

The add text query command adds the text query, and then it calls clearAllPaging().

Example - Using the add text query command

This add text query command adds a new text query for records with title containing african mammals,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.cmd=addTextQuery(Title\:\(african+mammals\))

Try It


Clear All Text Queries Command

Syntax

The syntax for the clear all text queries command is:

clearAllTextQueries()

This command takes no arguments.


Function

The clear all text queries command removes all text queries from the request, and then it calls clearAllPaging().

Example - Using the clear all text queries command

This clear all text queries command removes text queries, resets paging, and leaves everything else in the query:

  s.pn=3&s.ps=10&s.q=foreign&s.fvf=ContentType,Book&s.fq=trade+economy&s.cmd=clearAllTextQueries()

Try It


Remove Text Query Command

Syntax

The syntax for the remove text query command is:

removeTextQuery(<textQuery>)

There are no defaults for the removeTextQuery command.


Function

The remove text query command removes the text query, and then it calls clearAllPaging().

Example - Using the remove text query command

This remove text query command removes the text query for titles with african mammals,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.q=Title:(african+mammals)&s.cmd=removeTextQuery(Title\:\(african+mammals\))

Try It


Set Text Query Command

Syntax

The syntax for the set text query command is:

setTextQuery(<textQuery>)

There are no defaults for the setTextQuery command. Lucene escaping applies to this command. Characters that may need to be escaped include: +-&|!(){}[]^"~*?:\. Special characters only need to be escaped if their special meaning was not intended. Regular argument escaping must be applied after Lucene escaping.


Function

The set text query command adds the text query, replacing any existing text queries, and then it calls clearAllPaging().

Example - Using the set text query command

This set text query command adds a new text query for records with title containing african mammals,
and removes the text query for polar bears,
and it resets paging on the ContentType facet field and page number:

  s.pn=3&s.ff=ContentType,or,2,15&s.q=polar+bears&s.cmd=setTextQuery(Title\:\(african+mammals\))

Try It


Errors

Overview

The Search API may return five types of errors:

  • Authentication errors
  • Invalid Accept-type errors
  • Server-side errors
  • Client-side errors
  • End-user errors

The first two types of errors, authentication and invalid Accept-type errors, do not return any error response body. Invalid Accept-type errors return an HTTP 406, and authentication errors return an HTTP 401. In the case of a 401 or 406 error there will be an error message in the HTTP reason-phrase.

The final three error types all return error-response bodies. Server-side errors return an HTTP 500 status, and indicate a server-side failure. This can happen if the server is currently experiencing technical difficulties, or in the case of a malfunction. Client-side errors return an HTTP 400 status code, and indicate a coding error in the client. This will happen in the case of invalid syntax, incorrect encoding, incorrect escaping, or in general any error that causes the server to not be able to interpret the request. End-user errors may occur on normal responses with HTTP 200 status. Since end users will likely have no way of seeing the HTTP status, and viewable results may be returned regardless of an end-user error, these errors are simply included in the response payload. These errors may include things like bad query syntax within a search, even if the search request is correctly formed, escaped, and encoded.

Example - Client side 400 error

Bad query issued by client:
 
  s.cmd=addFacetField(foo)+fubar()
 
Response:
 
  <response>
    <errors>
      <error
       message="Error with command: addFacetField: Wrong number of arguments: 1"/>
      <error
       message="Error with command: fubar: Unknown command string: fubar"/>
    </errors>
  </response>

Try It


For more specific information on the error field format, see Errors Response Field.


Parameters

Overview

Queries to the Search API are made up of the following query parameters:

  • s.bookMark - Bookmark search - Searches for a record matching a previously stored bookmark
  • s.cmd - Command - Allows commands to be passed to the Search API
  • s.debug - Debug - Enables or disables debug mode
  • s.dym - Did You Mean - Enables or disables did you mean functionality
  • s.exp - Query Expansion - Enables or disables query expansion functionality
  • s.fids - Fetch Multiple IDs - Allows retrieval of multiple records by querying on a list of IDs in a single call.
  • s.ff - Facet Field - Allows facet counts for a given field with a given combine mode
  • s.fvf - Facet Value Filter - Applies an exact-value filter for a facet value within a facetable field
  • s.fvgf - Facet Value Group Filter - Advanced feature that allows grouping of facet values within a facet-value filter, using an arbitrary combine mode
  • s.he - Highlight End - Sets the end delimiter for result highlighting
  • s.hs - Highlight Start - Sets the starting delimiter for result highlighting
  • s.hl - Highlight - Enables or disables highlighting within result fields
  • s.ho - Holdings Only - Enables or disables holdings only mode
  • s.l - Language - Defines the language that is used in the user interface application
  • s.light - Light Weight Response - Enables or disables the light weight response format
  • s.mr (deprecated - see s.rec.db.max) - Max Recommendations - Define the maximum number of database recommendations to be presented in the results
  • s.oaf - Open Access Filter - Filters the results by open access content only
  • s.pn - Page Number - Controls the offset of the returned results within the total result set
  • s.ps - Page Size - Controls the number of results per page in the response
  • s.rec.db.max - Max Recommendations - Define the maximum number of database recommendations to be presented in the results
  • s.rec.topic.max - Maximum Topics - Determines how many topics to be returned by the Topic Explorer service
  • s.role - Role - Define the user as an authenticated user or not. Two options are 'authenticated' and 'none'
  • s.rff - Range Facet Field - Allows facet counts by range
  • s.rf - Range Filter - Allows inclusive and exclusive range filters on a single field
  • s.ru - Content Rollup - Defines which content rollups to activate and how many records to be included in each rollup
  • s.sort - Sort - Controls the result sort order
  • s.fq - Text Filter - Filter input allowing direct Lucene-style filter queries
  • s.q - Text Query - One of the primary query inputs. The Text Query parameter allows direct, Lucene-style queries

Token Parameters

Parameters that do not conform to the syntax in the previous heading, such as author=Mark+Twain, will be picked up by the parser and used to token replace values in other parameters.

Example - How token parameters get used

Initial query string:

  author=Mark+Twain&s.q=Author:(${author})

Results in:

  s.q=Author:(Mark+Twain)

Try It


For more information on token replacing, see Tokens.


Character Escaping

Characters must be escaped with the backslash ('\') character. For all parameter values except s.q and s.fq, the characters that must be escaped include: ,:\()${}. For parameters and arguments that hold Lucene query syntax, characters that may need to be escaped include: +-&amp;|!(){}[]^"~*?:\. Lucene special characters only need to be escaped if their special meaning was not intended. If Lucene escaping and regular escaping are both needed, as in the setTextQuery() command, the Lucene escaping must be performed before regular escaping.

All parameters must be properly URL-encoded using UTF-8 character encoding.

Example - An example query string

s.dym=true&
s.ff=ContentType%2Cor%2C1%2C1&
s.fvf=ContentType%2CJournal+Article%2Cfalse&
s.he=%3C%2Fh%3E&
s.hs=%3Ch%3E&
s.hl=true&
s.ho=true&
s.pn=1&
s.ps=10&
s.rff=PublicationDate%2C1990%3A2000&
s.rf=PublicationDate%2C1990%3A2000&
s.sort=PublicationDate%3Adesc&
s.fq=Title%3Arain&
s.q=forests

Try It








Command Parameter

Syntax

The syntax for the command parameter is:

s.cmd=<someCommand>[ <someCommand>]*

A query string may contain many s.cmd parameters, and each s.cmd parameter may contain may commands separated, by the space (' ') character. The order of s.cmd parameters within the query string and the order of commands within an s.cmd parameter are unimportant. Command names do not contain any special characters which would require escaping, but the following characters in the command arguments must be escaped: ,:\()${}


Function

The command parameter passes commands to the search api.

Example - Using the command parameter

This command clears all textQueries, searchTerms, textFilters, rangeFilters, facetValueFilters and paging,
then applies a textQuery of <span class="code">tropical rain forest</span> and requests ContentType facet counts:
   
  s.cmd=clearSearch()+setTextQuery(tropical+rain+forest)&s.cmd=addFacetField(ContentType,or,1,10)

Try It


Content Type Rollups Parameter

Syntax

This parameter is not yet available

The syntax for the query expansion parameter is:

s.ru=<string>:<integer>,<string>:<integer>,<string>:<integer>

A query string may contain only one s.ru parameter. The default value of this parameter is null. To disable a specific content type rollup, specify 0 as the integer for the specific rollup. There are three content type rollups available at this time: the newspaper rollup, the image rollup, and the reference rollup.


Function

The content type rollup parameter defines which content type rollups to activate and for each one, how many records will be included in the rollup.

Example - Using the s.ru parameter

This query string causes the news, images and reference content type rollups to be activated:
 
  s.q=heart+attack&s.ru=newspaper:3,image:10,reference:3

Response

"rollups": [
   "images" : {
      "position" : <position>,
      [ { Document-Fields }, { Document-Fields }, . . . ]
   },
   "newspapers" : {
      "position" : <position>,
      [ { Document-Fields }, { Document-Fields }, . . . ]
   },
   "references" : {
      "position" : <position>,
      [ { Document-Fields }, { Document-Fields }, . . . ]
   },
]


Try It


Debug Parameter

Syntax

The syntax for the debug parameter is:

s.debug=<boolean></boolean>

A query string may contain only one s.debug parameter. The default value of this parameter, if unspecified, is false.


Function

The debug parameter toggles internal debugging mode for the API. The data that is returned is generally only useful for internal debugging, and is not intended for display.

Example - Using the debug parameter

This query string causes debug info to be returned with the results:
 
  s.debug=true

Try It


Did You Mean Parameter

Syntax

The syntax for the did you mean parameter is:

s.dym-<boolean>

A query string may contain only one s.dym parameter. The default value of this parameter is true if the page number is one, all facet field page numbers are one and no filters are applied. Otherwise this parameter is fixed to false. This parameter cannot be used to override the default if the page number is not one, a facet field page number is not one or there are any filters applied.


Function

The did you mean parameter toggles Did You Mean suggestions on and off. Can be used to override the default of true when on page one with no filters applied.

Example - Using the dym parameter

This query string causes dym info to be returned with the results:
 
  s.q=govrnment&s.dym=true

Try It


Facet Field Parameter

Syntax

The syntax for the facet field parameter is:

s.ff=<facetField>, <combineMode>[, <pageNumber or whiteList>, <pageSize>]

A query string may contain many s.ff parameters. The default value for pageNumber is 1, if unspecified. The default value for pageSize is 10, if unspecified.

A whiteList has the form value1:value2:.... It specifies a set of facet values that are to be returned whether or not their counts are in the top pageSize, provided only that their counts are non-zero.


Function

The facet field parameter requests facet counts for a given facet field to be returned with results. This command can only be used on facetable fields.

Example - Using the facet field parameter

This query string causes facet counts for the ContentType field to be returned with the results:
 
  s.ff=ContentType,or,1,15

Try It


Example - Using the facet field parameter with a white list

This query string will return facet counts for the ContentType field including counts for Journal and eJournal, unless their counts are zero:

  s.ff=ContentType,or,Journal:eJournal,5

Try It


Facet Value Filter Parameter

Syntax

The syntax for the facet value filter parameter is:

s.fvf=<facetField>, <value>[, <negated>]

A query string may contain many s.fvf parameters. The default value for negated is false, if unspecified.


Function

The facet value filter parameter applies a facet value filter to the query. This parameter should always be used by applying values returned in a facet field from a previous query.

Example - Using the facet value filter parameter

This query string applies a facet value filter for ContentType "Book":
 
  s.fvf=ContentType,Book,false

Try It


Facet Value Group Filter Parameter

Syntax

The syntax for the facet value group filter parameter is:

s.fvgf=<facetField>, <combineMode>, <value>[, <value>]*

A query string may contain many s.fvgf parameters. There are no defaults for the s.fvgf parameter.


Function

The facet value group filter parameter is an advanced feature which allows applying filters for groups of facet values with an arbitrary combine mode. This parameter should always be used by applying values returned in a facet field from a previous query.

Example - Using the facet value group filter parameter

This query string applies a facet value group filter for SubjectTerms "north america" OR "u.s":
 
  s.fvgf=SubjectTerms,or,northern+america,u.s

Try It


Fetch Multiple IDs

Syntax

The syntax for the fetch multiple ids parameter is:

s.fids=<FETCH_ID>,<FETCH_ID>,<FETCH_ID>

Note: No more than 100 records can be requested per query.


Function

This parameter is to be used when needing to retrieve one or many records by ID.


Highlight End Parameter

Syntax

The syntax for the highlight end parameter is:

s.he=<value>

A query string may contain only one s.he parameter. The default value of this parameter, if unspecified, is </h>.


Function

The highlight end parameter sets the highlight end delimiter for highlighting in the response document fields.

Example - Using the highlight end parameter

This query string causes </em> to be used as the highlight end delimiter:
 
  s.q=highlight&s.hl=true&s.hs=<em>&s.he=</em>

Try It


Highlight Parameter

Syntax

The syntax for the highlight parameter is:

s.hl=<boolean>

A query string may contain only one s.hl parameter. The default value of this parameter, if unspecified, is true.


Function

The highlight parameter enables and disables highlighting in the response document fields.

Example - Using the highlight parameter

This query string turns off highlighting:

  s.q=highlight&s.hl=false

Try It


Highlight Start Parameter

Syntax

The syntax for the highlight start parameter is:

s.hs=<value>

A query string may contain only one s.hs parameter. The default value of this parameter, if unspecified, is <h>.


Function

The highlight start parameter sets the highlight start delimiter for highlighting in the response document fields.

Example - Using the highlight start parameter

This query string causes <em> to be used as the highlight start delimiter:

  s.q=highlight&s.hl=true&s.hs=<em>&s.he=</em>

Try It


Holdings Only Parameter

Syntax

The syntax for the holdings only parameter is:

s.ho=<boolean>

A query string may contain only one s.ho parameter. The default value of this parameter, if unspecified, is false.


Function

The holdings only parameter enables and disables holdings only mode.

Example - Using the holdings only parameter

This query string turns on holdings only mode:

  s.q=holdings&s.ho=true

Try It


Language Parameter

Syntax

The syntax for the language parameter is:

s.l=<string>

The language parameter may accept a 2 character ISO-639-1 language code.


Function

The language parameter will inform the Summon search engine which language is being used by the user to influence the search algorithms.

Example - Using the language parameter

s.l=en

Light Weight Response Parameter

Syntax

The syntax for the light weight response parameter is:

s.light=<boolean>

A query string may contain only one s.light parameter. The default value of this parameter, if unspecified, is false.


Function

The light weight response parameter allows you to enable a response format that contains less data for faster search results. The light weight response excludes multiple abstracts, table of contents and cited references from the results - elements commonly not used in search results that can also bloat the result response. By enabling the light weight response, the search results will load quicker and your application will require less memory allocation.

Example - Using the light weight response parameter

This query string turns on the light weight response mode:

  s.q=global+warming&s.light=true

Try It


Max Recommendations Parameter

Syntax

The syntax for the max recommendations parameter is:

s.rec.db.max=<integer>

s.mr=<integer> (deprecated)

A query string may contain only one s.rec.db.max parameter. The default value of this parameter, if unspecified, is 2.


Function

The max recommendations parameter defines the maximum number of database recommendations to include in the results.

Example - Using the max recommendations parameter

This query string requests up to 3 database recommendations:

  s.q=nursing&s.rec.db.max=3

Try It


Maximum Topics Parameter

Syntax

The syntax for the query expansion parameter is:

s.rec.topic.max=<integer>

A query string may contain only one s.rec.topic.max parameter. The default value of this parameter is  .


Function

The maximum topics parameter defines the maximum number of topics will be returned in the search result. Currently, this parameter only supports 0 or 1 as input.

Example - Using the s.rec.topic.max parameter

This query string enables the topic service to return a maximum of 1 topic for the search:
 
  s.q=heart+attack&s.rec.topic.max=1

Try It


Page Number Parameter

Syntax

The syntax for the page number parameter is:

s.pn=<pageNumber>

A query string may contain only one s.pn parameter. The default value of this parameter, if unspecified, is 1. The maximum value of this parameter is 50 and the maximum number of records is 1000.


Function

The page number parameter works with the page size parameter to control the offset of the records returned in the results.

Example - Using the page number parameter

This query string returns documents 16 to 30 of the total result set:

  s.pn=2&s.ps=15

Error Messages

  {
    "errors": [
        {
            "code": "page.number.too.large",
            "message": "Maximum supported page number is 50 (provided number is 51)."
        }
    ],
    "sessionId": "48eba240-3d05-4e6c-b0f2-3bd30b34b5bd",
    "spotlightPosition": 0,
    "version": "2.0.0"
  }

  {
    "errors": [
        {
            "code": "results.size.too.large",
            "message": "Maximum supported returned results set size is 1000 (provided size is 1050)."
        }
    ],
    "sessionId": "48eba240-3d05-4e6c-b0f2-3bd30b34b5bd",
    "spotlightPosition": 0,
    "version": "2.0.0"
  }

Try It


Page Size Parameter

Syntax

The syntax for the page size parameter is:

s.ps=<pageSize>

A query string may contain only one s.ps parameter. The default value of this parameter, if unspecified, is 15. The maximum value of this parameter is 50 and the maximum number of records possible is 1000.


Function

The page size parameter works with the page number parameter to control the offset of the records returned in the results. It also controls how many results are returned with each request.

Example - Using the page size parameter

This query string returns documents 5 to 8 of the total result set:
 
  s.pn=2&s.ps=4

Error Messages

  {
    "errors": [
        {
            "code": "page.size.too.large",
            "message": "Maximum supported page size is 50 (provided size is 51)."
        }
    ],
    "sessionId": "48eba240-3d05-4e6c-b0f2-3bd30b34b5bd",
    "spotlightPosition": 0,
    "version": "2.0.0"
  }

  {
    "errors": [
        {
            "code": "results.size.too.large",
            "message": "Maximum supported returned results set size is 1000 (provided size is 1050)."
        }
    ],
    "sessionId": "48eba240-3d05-4e6c-b0f2-3bd30b34b5bd",
    "spotlightPosition": 0,
    "version": "2.0.0"
  }

Try It


Query Expansion Parameter

Syntax

The syntax for the query expansion parameter is:

s.exp=<boolean>

A query string may contain only one s.exp parameter. The use of this parameter also requires the use of the s.l parameter. The default value of this parameter is false, but should be set to true for all queries. When the user wants to turn this feature off, the parameter would then be set to false.


Function

The query expansion parameter toggles the synonym mapping of user queries on and off.

Example - Using the s.exp parameter

This query string causes the user's query to be expanded with matching synonyms in the search results:
 
  s.q=heart+attack&s.exp=true&s.l=en

Response

{
   "queryExpansion" : {
      "isExpanded" : "true",
      "searchTerms" : [ "search", "term", "list" ]
   }
}


Try It


Range Facet Field Parameter

Syntax

The syntax for the range facet field parameter is:

s.rff=<facetField>, <minValue>:<maxValue>[:<inclusive>][, <minValue>:<maxValue>[:<inclusive>]]*

A query string may contain many s.rff parameters. The default value for inclusive is true, if unspecified.


Function

The range facet field parameter requests facet counts, for a given set of ranges, in a given facet field, to be returned with results.

Example - Using the range facet field parameter

This query string causes range facet counts for several ranges in the PublicationDate_dt field to be returned with the results:

  s.rff=PublicationDate,1971:1980,1981:1990,1991:2000,2001:2010

Try It


Range Filter Parameter

Syntax

The syntax for the range filter parameter is:

s.rf=<fieldName>, <minValue>:<maxValue>[:<inclusive>]

A query string may contain many s.rf parameters. The default value for inclusive is true, if unspecified.


Function

The range filter parameter applies a range filter to the query. This parameter will often be used by applying values returned in a range facet field from a previous query.

Example - Using the range filter parameter

This query string filters on results with publication dates between 1971 and 1980:

  s.rf=PublicationDate,1971:1980

Try It


Role Parameter

Syntax

The syntax for the role parameter is:

s.role=<string>

A query string may contain only one s.role parameter. There are two possible values for this parameter, either authenticated or none. The default value of this parameter, if unspecified, is none.


Function

The role parameter controls whether the search should be done as an authenticated user or an unauthenticated user. This is used to display content from A&I indexes that can only be displayed to authenticated users. Please respect this control and only use the authenticated for authenticated users only.

Example - Using the holdings only parameter

This query string turns on holdings only mode:

  s.q=nursing&s.role=authenticated

Try It


Sort Parameter

Syntax

The syntax for the sort parameter is:

s.sort=<fieldName>:<sortOrder>[, <fieldName>:<sortOrder>]*

A query string may contain only one s.sort parameter. The default sort order is sort by relevancy, if unspecified.


Function

The sort parameter sets the order which results are returned within a result set.

Example - Using the sort parameter

This query string causes the results to be returned in order of publication date descending:

  s.sort=PublicationDate:desc

Try It


Text Filter Parameter

Syntax

The syntax for the text filter parameter is:

s.fq=<filterQuery>

A query string may contain many s.fq parameters. There are no defaults for the s.fq parameter. Lucene escaping applies to this parameter. Characters that may need to be escaped include: +-&amp;|!(){}[]^"~*?:\. Special characters only need to be escaped if their special meaning was not intended.


Function

The text filter parameter is used to apply reusable text filters to queries. Unlike text queries, text filters do not affect document relevance score. Text filters are useful when a facet value filter is not available to narrow the search, and multiple queries need to be run inside the same limiting scope, without the limiting scope affecting relevance scores.

Example - Using the text filter parameter

This query limits to documents about trade and economy:

  s.fq=trade+economy

Try It


Text Query Parameter

Syntax

The syntax for the text query parameter is:

s.q=<textQuery>

A query string may contain many s.q parameters. They will be combined with the AND operator. There are no defaults for the s.q parameter. Lucene escaping applies to this parameter. Characters that may need to be escaped include: +-&amp;|!(){}[]^"~*?:\. Special characters only need to be escaped if their special meaning was not intended.


Function

The text query parameter is a primary query parameter and allows searching using raw Lucene syntax.

Example - Using the text query parameter

This query searches for documents with a title containing canadian politics:

  s.q=Title:(canadian+politics)

Try It


Quick Reference

Query Parameters

Type Syntax Defaults Occurrence
Text Query s.q=<textQuery>   many
Text Filter s.fq=<filterQuery>   many
Range Filter s.rf=<fieldName>, <minValue>:<maxValue>[:<inclusive>] inclusive=true many
Facet Value Filter s.fvf=<facetField>, <value>[, <negated>]   many
Facet Value Group Filter s.fvgf[<id>]=<facetField>, <combineMode>, <value1>, <value2>...   many
Facet Field s.ff=<facetField>, <combineMode>[, <pageNumber>, <pageSize>] pageNumber=1, pageSize=10 many
Range Facet Field s.rff=<fieldName>, <minValue1>:<maxValue1>[:<inclusive1>], <minValue2>:<maxValue2>[:<inclusive2>]... inclusive=true many
Page Number s.pn=<pageNumber> pageNumber=1 once
Page Size s.ps=<pageSize> pageSize=15 once
Sort s.sort=<field1>:<order>, <field2>:<order>... sortByRelevancy once
Highlight s.hl=<boolean> true once
Highlight Start s.hs=<value> <h> once
Highlight End s.he=<value> </h> once
Debug s.debug=<boolean> false once
Did You Mean s.dym=<boolean> true once
Holdings Only s.ho=<boolean> false once
Open Access Filter s.oaf=<boolean> false once
Command s.cmd=<someCommand>   many

Commands

Command Effects
Global Commands
clearAll() Resets the entire query as if passing an empty query string
clearSearch() Calls clearAllTextQueries() clearAllSearchTerms() clearAllTextFilters() clearAllRangeFilters() clearAllFacetValueFilters() clearAllPaging().
i.e. Reset the search but leave sort order, params, flags, page size and facet fields intact.
setDidYouMean(<boolean>) True by default whenever setTextQuery() addTextQuery() setSearchTerm() addSearchTerm() are called. Can be used to counter that default.
setDebugging(<boolean>) Toggles debug mode
setHighlighting(<boolean>) Toggles highlighting
setHighlightDelimiters(<startValue>, <endValue>) Sets highlighting delimiters
setHoldingsOnly(<boolean>) Toggles holdings only mode and calls clearAllPaging()
Paging Commands
clearAllPaging() Sets query.pageNumber=1 and calls clearAllFacetPaging()
clearAllFacetPaging() Sets facetField.pageNumber=1 for each facet field
removeFacetPaging(<facetField>) Sets facetField.pageNumber=1 for a given facet field
setPageSize(<pageSize>) Sets query.pageSize=<pageSize> and calls clearAllPaging()
setFacetPageSize(<facetField>, <pageSize>) Sets facetField.pageSize=<pageSize> for a given facet field and calls removeFacetPaging(<facetField>)
goToPage(<pageNumber>) Sets query.pageNumber=<pageNumber> and calls clearAllFacetPaging()
movePage(<pageDelta>) Calls goToPage(query.pageNumber + <pageDelta>)
nextPage() Calls movePage(1)
previousPage() Calls movePage(-1)
goToFacetPage(<facetField>, <pageNumber>) Sets facetField.pageNumber=<pageNumber>
moveFacetPage(<facetField>, <pageDelta>) Calls goToFacetPage(<facetField>, facetField.pageNumber + <pageDelta>)
nextFacetPage(<facetField>) Calls moveFacetPage(<facetField>, 1)
previousFacetPage(<facetField>) Calls moveFacetPage(<facetField>, -1)
Text Query Commands
clearAllTextQueries() Clears all text queries and calls clearAllPaging()
removeTextQuery(<textQuery>) Removes <textquery> and calls clearAllPaging()
setTextQuery(<textQuery>) Replaces all text queries with <textquery> and calls clearAllPaging()
addTextQuery(<textQuery>) Adds <textquery> and calls clearAllPaging()
Text Filter Commands
clearAllTextFilters() Clears all text filters and calls clearAllPaging()
removeTextFilter(<textFilter>) Removes <textfilter> and calls clearAllPaging()
setTextFilter(<textFilter>) Replaces all text filters with <textfilter> and calls clearAllPaging()
addTextFilter(<textFilter>) Adds <textfilter> and calls clearAllPaging()
Range Filter Commands
clearAllRangeFilters() Clears all range filters and calls clearAllPaging()
removeRangeFilter(<fieldName>[, <minValue>:<maxValue>:<inclusive>]) Removes range filters by <fieldname> or <fieldname>, <minvalue>, <maxvalue>, <inclusive> if all arguments are present and calls clearAllPaging()
setRangeFilter(<fieldName>, <minValue>:<maxValue>[:<inclusive>]) Replaces all range filters with the new range filter and calls clearAllPaging()
addRangeFilter(<fieldName>, <minValue>:<maxValue>[:<inclusive>]) Adds the new range filter and calls clearAllPaging()
Facet Value Filter Commands
clearAllFacetValueFilters() Clears all facet value and group filters and calls clearAllPaging()
removeFacetValueFilter(<facetField>[, <value>]) Removes facet value filters by <facetfield> or <facetfield>, <value> if both arguments are present and calls clearAllPaging()
removeFacetValueGroupFilter(<id>[, <value>]) Removes facet group filters by <id> or <id>, <value> if both arguments are present and calls clearAllPaging()
setFacetValueFilters(<facetField>, <value>[: <negated>][, <value>[: <negated>]]*) Replaces all facet value and facet group filters with the new facet value filter and calls clearAllPaging()
addFacetValueFilters(<facetField>, <value>[: <negated>][, <value>[: <negated>]]*) Adds the new facet value filter and calls clearAllPaging()
addFacetValueGroupFilter(<facetField>, <combineMode>, <value1>, <value2>...) Adds the new facet value group filter and calls clearAllPaging()
negateFacetValueFilter(<facetField>[, <value>]) Negates facet value filters by <facetfield> or <facetfield>, <value> and calls clearAllPaging()
Sort Commmands
setSortByRelevancy() Clears all sort fields and calls clearAllPaging()
setSort(<sortField1>:<sortDirection1>, <sortField2>:<sortDirection2>...) Sets sort fields and calls clearAllPaging()
reverseSortOrder() Reverses the order of each sort field and calls clearAllPaging()
Facet Field Commands
clearAllFacetFields() Clears all facet fields
removeFacetField(<facetField>) Removes the indicated facet field and calls clearAllFacetPaging()
addFacetField(<facetField>, <combineMode>[, <pageNumber>, <pageSize>]) Adds a new facet field with given combine mode, page number and page size or the defaults and calls clearAllFacetPaging()
addRangeFacetField(<facetField>, <minValue1>:<maxValue1>[:<inclusive1>], <minValue2>:<maxValue2>:[<inclusive2>]...) Adds a facet field for the given set of ranges and calls clearAllFacetPaging()
listFacetValues(<facetField>, <combineMode>) Adds the facet field and calls clearAllFacetFields() setPageSize(0) setHighlighting(false) setParameter(countFullText, false) addFacetField(<facetField>, <combineMode>, 1, 100)

Response

Overview

The response currently comes in two formats:

  • JSON
  • XML

Both response formats contain the same major fields, which include:

  • sessionId - the session ID for the current request
  • elapsedQueryTime - the time spent waiting for the query to return from the search engine
  • queryTime - the time the search engine spent processing the query
  • totalRequestTime - the total time taken to process the request, including time to format the results
  • pageCount - the total number of available pages for the current query
  • didYouMeanSuggestions - suggestions for spelling corrections including the term being corrected and its suggested replacement
  • recommendationLists - recommendations for databases and best bets that arebased on the user's input
  • documents - the meta documents themselves
  • errors - any server, client or end-user errors
  • facetFields - counts for any facet fields requested
  • query - a parsed format of the query submitted after commands are applied
  • rangeFacetFields - counts for any range facet fields requested

For more specific information on each field, see didYouMeanSuggestions, recommendationLists, documents, errors, facetFields, query and rangeFacetFields.

XML Format

In the XML format, the root element is response. All simple types are stored as attributes, and only complex types are stored as nested elements. Lists of elements are stored under a nested element unless the containing element only has one list. For example, the query element contains nested elements for textQueries, searchTerms, textFilters, rangeFilters, facetValueFilters, facetValueGroupFilters, facetFields, rangeFacetFields, sort and params, because the query element contains more than one list. The rangeFacetField, on the other hand, does not have a nested element for ranges, because ranges is the only list on rangeFacetField. Each range element is stored directly on the rangeFacetField.

Example - An XML result snippet

<query
 queryString="s.rff=PublicationDate%2C1981%3A1990%2C1991%3A2000&amp;s.q=tropics&amp;s.dym=true"
 isDidYouMeanEnabled="true">
  <textQueries>
    <textQuery
     textQuery="tropics"
     removeCommand="removeTextQuery(tropics)"/>
  </textQueries>
  <didYouMeanSuggestions/>
  <recommendationLists/>
  <searchTerms/>
  <textFilters/>
  <rangeFilters/>
  <facetValueFilters/>
  <facetValueGroupFilters/>
  <facetFields/>
  <rangeFacetFields>
    <rangeFacetField
     fieldName="PublicationDate"
     removeCommand="removeFacetField(PublicationDate)">
      <range minValue="1981" maxValue="1990"/>
      <range minValue="1991" maxValue="2000"/>
    </rangeFacetField>
  </rangeFacetFields>
  <sort/>
  <params/>
</query>

JSON Format

In the JSON format, the object itself is the root. Extra nesting is avoided where possible. Objects inside arrays do not have an extra level of wrapping containing the object name. Numbers and Booleans are stored as their appropriate JavaScript types.

Example - A JSON result snippet

"rangeFacetFields":[
  {
    "fieldName":"PublicationDate_dt",
    "displayName":"PublicationDate",
    "removeCommand":"removeFacetField(PublicationDate)",
    "counts":[
      {
        "range":{
          "minValue":"1981",
          "maxValue":"1990"
        },
        "count":4570,
        "isApplied":false,
        "applyCommand":"addRangeFilter(PublicationDate,1981:1990)"
      },
      {
        "range":{
          "minValue":"1991",
          "maxValue":"2000"
        },
        "count":3817,
        "isApplied":false,
        "applyCommand":"addRangeFilter(PublicationDate,1991:2000)"
      }
    ]
  }
]

Did You Mean Suggestions Response Field

The didYouMeanSuggestions field will be populated if the query is eligible for did you mean suggestions, and the primary query contains terms which drop the response document count below a certain threshold, and there are likely alternatives to the limiting terms. Each suggestion contains the following three fields:

  • originalQuery - the query that would be replaced by applying the did you mean suggestion
  • suggestedQuery - the query that would replace the originalQuery if the suggestion was applied
  • newSearchCommand - a command that can be appended to the existing query string to apply the did you mean suggestion.

Example - A didYouMeanSuggestions element in XML format

<didYouMeanSuggestions>
  <suggestion
   originalQuery="franknestein"
   suggestedQuery="frankenstein"
   newSearchCommand="setTextQuery(frankenstein)"/>
</didYouMeanSuggestions>

Example - A didYouMeanSuggestions object in JSON format

"didYouMeanSuggestions":[
  {
    "originalQuery":"franknestein",
    "suggestedQuery":"frankenstein",
    "newSearchCommand":"setTextQuery(frankenstein)"
  }
]

Documents Response Field

The documents field will be populated if there are any meta documents to return. Each document has five fields:

  • hasFullText - boolean which indicates if a given document has full text available
  • inHoldings - boolean which indicates if a given document is in the current library's holdings
  • availabilityToken - optional - a string which identifies a given document's lookup key for use with the Availability API
  • openUrl - an OpenURL describing a given document
  • fields - the fields on the document. In XML format this is the only list on the document object. Therefore, the field elements are all direct children of the document

Each field in the fields list has a name and a list of values. The values may be either plain strings or a custom micro format. The micro formats are parsed in the response so even though micro formats are XML. They will be returned as JSON when response type is JSON. Some documents will have thumbnails available. Thumbnail URLs are returned in the thumbnail_s, thumbnail_m and thumbnail_l fields. Thumbnails may be referenced directly in the rendered page, and do not require another API call. If a request is made for a thumbnail that no longer exists, a redirect will be returned to a 1x1px transparent gif.

Example - A documents element in XML format

<documents>
  <document
     hasFullText="false"
     isFullTextHit="false"
     inHoldings="false">
    <field name="Language">
      <value>English</value>
    </field>
    <field name="PublicationPlace">
      <value>Chicago, Ill</value>
    </field>
    <field name="Score">
      <value>1.0</value>
    </field>
    <field name="PageCount">
      <value>1</value>
    </field>
    <field name="Copyright">
      <value>Copyright Chicago Tribune Co. Aug 3, 1980</value>
    </field>
    <field name="IsPeerReviewed">
      <value>false</value>
    </field>
    <field name="PublicationDate_xml">
      <datetime text="19800803" month="08" year="1980" day="03"/>
    </field>
    <field name="PublicationCentury">
      <value>1900</value>
    </field>
    <field name="PublicationDate">
      <value>19800803</value>
    </field>
    <field name="Copyright_xml">
      <copyright notice="Copyright Chicago Tribune Co. Aug 3, 1980"/>
    </field>
    <field name="Snippet">
      <value>RED CEDAR hand-split shakes and shingles offer many design options for an interior wallcovering that has a texture that won&apos;t quit.</value>
    </field>
    <field name="NewspaperSection">
      <value>S</value>
    </field>
    <field name="IsScholarly">
      <value>false</value>
    </field>
    <field name="ID">
      <value>FETCH-proquest_dll_6216115920</value>
    </field>
    <field name="PublicationTitle">
      <value>Chicago Tribune (1963-Current file)</value>
    </field>
    <field name="PCID">
      <value>6756202</value>
    </field>
    <field name="Genre">
      <value>article</value>
    </field>
    <field name="PublicationPlace_xml">
      <location name="Chicago, Ill"/>
    </field>
    <field name="PublicationDecade">
      <value>1980</value>
    </field>
    <field name="PQID">
      <value>621611592</value>
    </field>
    <field name="Abstract">
      <value>RED CEDAR hand-split shakes and shingles offer many design options for an interior wallcovering that has a texture that won&apos;t quit.</value>
    </field>
    <field name="ContentType">
      <value>Newspaper Article</value>
    </field>
    <field name="Title">
      <value>Outdoor coverings make a move inside</value>
    </field>
    <field name="ISSN">
      <value>1085-6706</value>
    </field>
    <field name="SSID">
      <value>ssj0016743</value>
    </field>
    <field name="StartPage">
      <value>S_A6</value>
    </field>
    <field name="link">
<value>http://demo.summon.serialssolutions.com/link/eJxtkd9q2zAUxp11G2u3vcXSG6NEkv9UMpiSJQR6UUppS8tujCYfJ0ptKZXkNM_RJ67iwGDQCyF9P33nnA8pin7RXDSEJimSBEuUUpIiJlKKJGdpSrIaMs5G0dndLFs8sutb_vRp9Lb2fltMp05k9SvrXvh-4kBYuQ6bVaJ1zrS9V0a7iTTdpfT7age2_JPwCWOIYpyeHxhoWSrdmHEyM40a02UA4fxwv0Ts3Da2UvVwXzhVT13fdUZ_OCB4fbUTbdV0_lgQ2k2DKJ5hV3R-X2xMb7VoD8bJCrSFUsOrG6TwyrdQ3vS-NsbG0oSkSq9c3IlniEXcBRArHSLA4N8c_fO1kmJl4nur_vYa4jFlhOcJmvfWgvZxo1oYUz6U1MJDSTjDCDOEk4Ep53RJMMtQfoHzAbmtWEF5V82OEvYeDqEXv68WpQ6vI_7HRgaeU5ITknF6En2m4Re_RGfObTAm-UWafI1O_034Hn3bWvPSg_M_ohH5GdY7LE6hqQ</value>
    </field>
    <isSpotlightParent>false</isSpotlightParent>
  </document>
</documents>

Example - A documents object in JSON format

[documents] => Array
        (
            [0] => Array
                (
                    [hasFullText] =>
                    [isFullTextHit] =>
                    [inHoldings] =>
                    [Language] => Array
                        (
                            [0] => English
                        )
                    [PublicationPlace] => Array
                        (
                            [0] => Boston, Mass
                        )
                    [Score] => Array
                        (
                            [0] => 1.0
                        )
                    [PageCount] => Array
                        (
                            [0] => 1
                        )
                    [Copyright] => Array
                        (
                            [0] => Copyright New York Times Company Jul 7, 1899
                        )
                    [IsPeerReviewed] => Array
                        (
                            [0] => false
                        )
                    [PublicationDate_xml] => Array
                        (
                            [0] => Array
                                (
                                    [text] => 18990707
                                    [month] => 07
                                    [year] => 1899
                                    [day] => 07
                                )
                        )
                    [PublicationCentury] => Array
                        (
                            [0] => 1800
                        )
                    [PublicationDate] => Array
                        (
                            [0] => 18990707
                        )
                    [Copyright_xml] => Array
                        (
                            [0] => Array
                                (
                                    [notice] => Copyright New York Times Company Jul 7, 1899
                                )
                        )
                    [Snippet] => Array
                        (
                            [0] => CLEVELAND, O. July 6--That the Standard oil company, as an Ohio corporation, will soon cease to exist is shown by the fact that the immense refinery plant, the ...
                        )
                    [GeographicLocations] => Array
                        (
                            [0] => CLEVELAND, O. July 6
                        )
                    [IsScholarly] => Array
                        (
                            [0] => false
                        )
                    [ID] => Array
                        (
                            [0] => FETCH-proquest_dll_5479701420
                        )
                    [PublicationTitle] => Array
                        (
                            [0] => Boston daily globe (Boston, Mass. : 1872)
                        )
                    [PCID] => Array
                        (
                            [0] => 6477782
                        )
                    [Genre] => Array
                        (
                            [0] => article
                        )
                    [PublicationPlace_xml] => Array
                        (
                            [0] => Array
                                (
                                    [name] => Boston, Mass
                                )
                        )
                    [PublicationDecade] => Array
                        (
                            [0] => 1890
                        )
                    [PQID] => Array
                        (
                            [0] => 547970142
                        )
                    [Abstract] => Array
                        (
                            [0] => CLEVELAND, O. July 6--That the Standard oil company, as an Ohio corporation, will soon cease to exist is shown by the fact that the immense refinery plant, the second largest in the world, strung along in the valley of...
                        )
                    [ContentType] => Array
                        (
                            [0] => Newspaper Article
                        )
                    [Title] => Array
                        (
                            [0] => LEAVING THE STATE OF OHIO
                        )
                    [SSID] => Array
                        (
                            [0] => ssj0043126
                        )
                    [StartPage] => Array
                        (
                            [0] => 7
                        )
                    [Subtitle] => Array
                        (
                            [0] => Standard Oil Company Abandoning Its Cleveland Plant--Official, However, Makes an Implied Denial
                        )
                    [link] => Array
                        (
                            [0] => http://demo.summon.serialssolutions.com/link/eJxtkG1vgjAQx3EPyeK2bzF804C0ILQkZNGp02TOLLKH7I2pUBQHVGlRl335VXy1ZMk1d_e7_13b07Q7D-OFS1zX8JANDceGkUFo4hh4YbkWgdSNGGxozVm303_Hkxfycdb4WUm58dttQTvxHudbcjAFo2W0Uq5MaSYEzyqZ8kKYEc_vI3mY71gZfNrExNhAluW0jowVUZAWCdftLk9SHQ0VUPFrODRwq0zKeRrXdV-kcVtUec6Lfy9QWjnf0Wye5PLUoMa1VeJ_sZ2fy4O_5lVZ0OwoNJesKFlQsL2oUypTmbHgadB9Gz8_gnA0ALOwGw7AdAimo_G0Fq1Poh4Xkhcgpmn2DZYZXzCgI3yiOnoAEyqECdQXAMQe0hGpm2MqWQAxIYblKauZ2NAlC04xO0h2fF2_N-4Has6Q_sU8UrzjeMSzoIPOtQsEkX2pNYVYq03aELnX2tWm5NuKCXmjNeCtOr98FJTO
                        )
                )
        )
)

Errors Response Field

The errors field will be populated if there are any server, client or end user errors. Each error has two fields:

  • message - string which describes the error
  • suggestion - optional - a suggestion is made up of three fields: originalText, suggestedText and applySuggestionCommand

Example - An errors element in XML format

<errors>
  <error
   message="Attempting to search within field which does not exist: recidivism">
    <suggestion
     originalText="Probability models of recidivism:an exploration"
     suggestedText="Probability models of recidivism\:an exploration"
     applySuggestionCommand="setTextQuery(Probability models of recidivism\\:an exploration)">
  </error>
</errors>

Example - An errors object in JSON format

"errors":[
  {
    "message":"Attempting to search within field which does not exist: recidivism",
    "suggestion":{
      "originalText":"Probability models of recidivism:an exploration",
      "suggestedText":"Probability models of recidivism\\:an exploration",
      "applySuggestionCommand":"setTextQuery(Probability models of recidivism\\:an exploration)"
    }
  }
]

Facet Fields Response Field

The facetFields field will be populated if if any facet field counts were requested in the query. Each facetField contains the following 9 fields:

  • fieldName - the name of the field being faceted on
  • displayName - the human friendly name of the field being faceted on
  • combineMode - the mode with which the value filters were applied for the counts
  • pageNumber - the current page number for the counts
  • pageSize - the current page size for the counts
  • hasLimitingValue - whether or not this facet field has any potentially limiting value filters
  • hasAppliedValue - whether or not this facet field has any currently applied value filters
  • removeCommand - command to remove this facet field from the list of requested facet fields
  • counts - list of the facetCount items for the individual facet values

Each facetCount contains the following 9 potential fields:

  • value - the text value for this count
  • count - the document count
  • isApplied - whether or not there is a facet value filter already applied for this facet value
  • isNegated - whether or not the associated facet value filter is currently negated
  • isFurtherLimiting - whether or not this facet value filter could further refine the result set
  • applyCommand - available if not isApplied - the command to apply a facet value filter for this facet value
  • applyNegatedCommand - available if not isApplied - the command to apply a negative facet value filter for this facet value
  • removeCommand - available if isApplied - the command to remove the facet value filter for this facet value
  • negateCommand - available if isApplied - the command to negate the facet value filter for this facet value

The counts field is the only list on facetField, so there is no nested element for it.

Example - A facetFields element in XML format

<facetFields>
  <facetField
   fieldName="ContentType_sfacet"
   displayName="ContentType"
   combineMode="or"
   pageNumber="1"
   pageSize="10"
   hasLimitingValue="true"
   hasAppliedValue="true"
   removeCommand="removeFacetField(ContentType)"
   listValuesCommand="listFacetValues(ContentType,or)"
   removeValueFiltersCommand="removeFacetValueFilter(ContentType)">
    <facetCount
     value="Journal"
     count="74926"
     isApplied="true"
     isNegated="false"
     isFurtherLimiting="true"
     removeCommand="removeFacetValueFilter(ContentType,Journal)"
     negateCommand="negateFacetValueFilter(ContentType,Journal)"/>
    <facetCount
     value="Book"
     count="1984"
     isApplied="true"
     isNegated="false"
     isFurtherLimiting="true"
     removeCommand="removeFacetValueFilter(ContentType,Book)"
     negateCommand="negateFacetValueFilter(ContentType,Book)"/>
    <facetCount
     value="Newspaper"
     count="1012"
     isApplied="false"
     isNegated="false"
     isFurtherLimiting="true"
     applyCommand="addFacetValueFilter(ContentType,Newspaper,false)"
     applyNegatedCommand="addFacetValueFilter(ContentType,Newspaper,true)"/>
  </facetField>
</facetFields>

Example - A facetFields object in JSON format

"facetFields":[
  {
    "fieldName":"ContentType_sfacet",
    "displayName":"ContentType",
    "combineMode":"or",
    "pageNumber":1,
    "pageSize":10,
    "hasLimitingValue":true,
    "hasAppliedValue":true,
    "removeCommand":"removeFacetField(ContentType)",
    "listValuesCommand":"listFacetValues(ContentType,or)",
    "removeValueFiltersCommand":"removeFacetValueFilter(ContentType)",
    "counts":[
      {
        "value":"Journal",
        "count":115206,
        "isApplied":true,
        "isNegated":false,
        "isFurtherLimiting":true,
        "removeCommand":"removeFacetValueFilter(ContentType,Journal)",
        "negateCommand":"negateFacetValueFilter(ContentType,Journal)"
      },
      {
        "value":"Book",
        "count":3608,
        "isApplied":true,
        "isNegated":false,
        "isFurtherLimiting":true,
        "removeCommand":"removeFacetValueFilter(ContentType,Book)",
        "negateCommand":"negateFacetValueFilter(ContentType,Book)"
      },
      {
        "value":"Newspaper",
        "count":2384,
        "isApplied":false,
        "isNegated":false,
        "isFurtherLimiting":true,
        "applyCommand":"addFacetValueFilter(ContentType,Newspaper,false)",
        "applyNegatedCommand":"addFacetValueFilter(ContentType,Newspaper,true)"
      }
    ]
  }
]

Query Response Field

The query field will be populated for all queries except when the HTTP status is 400 or 500. The query contains the following 18 fields:

  • queryString - the current query string, after commands were applied
  • pageNumber - the current page number
  • pageSize - the current page sizes
  • isHighlightingEnabled - whether or not highlighting is currently turned on
  • highlightStartDelimiter - the current highlight start delimiter
  • highlightEndDelimiter - the current highlight end delimiter
  • isDidYouMeanEnabled - whether or not did you mean is currently turned on
  • isDebugEnabled - whether or not debug is currently turned on
  • isHoldingsOnlyEnabled - whether or not holdings only mode is currently turned on
  • textQueries - list of the textQuery items in the current query
  • textFilters - list of the textFilter items in the current query
  • rangeFilters - list of the rangeFilter items in the current query
  • facetValueFilters - list of the facetValueFilter items in the current query
  • facetValueGroupFilters - list of the facetValueGroupFilter items in the current query
  • facetFields - list of the facetField items in the current query
  • rangeFacetFields - list of the rangeFacetField items in the current query
  • sort - the sort order of the current query

Example - A query element in XML format

<query
 queryString="s.fvgf%3A1=ContentType%2Cor%2CBook%2CJournal+Article&amp;s.hs=%3Ch%3E&amp;s.ho=true&amp;s.fq=Title%3Arain&amp;s.sort=PublicationDate%3Adesc&amp;s.rff=PublicationDate%2C1990%3A2000&amp;s.ps=10&amp;s.debug=false&amp;s.dym=true&amp;s.pn=1&amp;s.rf=PublicationDate%2C1990%3A2000&amp;s.ff=ContentType%2Cor%2C1%2C1&amp;s.hl=true&amp;s.q=forests&amp;s.he=%3C%2Fh%3E&amp;s.fvf=ContentType%2CJournal+Article%2Cfalse"
 pageNumber="1"
 pageSize="10"
 isHighlightingEnabled="true"
 highlightStartDelimiter="&lt;h&gt;"
 highlightEndDelimiter="&lt;/h&gt;"
 isDidYouMeanEnabled="true"
 isDebugEnabled="false"
 isHoldingsOnlyEnabled="true">
  <textQueries>
    <textQuery
     textQuery="forests"
     removeCommand="removeTextQuery(forests)"/>
  </textQueries>
  <textFilters>
    <textFilter
     textFilter="Title:rain"
     removeCommand="removeTextFilter(Title:rain)"/>
  </textFilters>
  <rangeFilters>
    <rangeFilter
     fieldName="PublicationDate"
     removeCommand="removeRangeFilter(PublicationDate,1990:2000)">
      <range
       minValue="1990"
       maxValue="2000"/>
    </rangeFilter>
  </rangeFilters>
  <facetValueFilters>
    <facetValueFilter
     fieldName="ContentType"
     value="Journal Article"
     isNegated="false"
     removeCommand="removeFacetValueFilter(ContentType,Journal Article)"
     negateCommand="negateFacetValueFilter(ContentType,Journal Article)"/>
  </facetValueFilters>
  <facetValueGroupFilters>
    <facetValueGroupFilter
     tag="1"
     fieldName="ContentType"
     combineMode="or"
     removeCommand="removeFacetValueGroupFilter(1)">
      <facetValue
       value="Book"
       removeCommand="removeFacetValueGroupFilter(1,Book)"/>
      <facetValue
       value="Journal Article"
       removeCommand="removeFacetValueGroupFilter(1,Journal Article)"/>
    </facetValueGroupFilter>
  </facetValueGroupFilters>
  <facetFields>
    <facetField
     fieldName="ContentType"
     combineMode="or"
     pageNumber="1"
     pageSize="1"
     removeCommand="removeFacetField(ContentType)"/>
  </facetFields>
  <rangeFacetFields>
    <rangeFacetField
     fieldName="PublicationDate"
     removeCommand="removeFacetField(PublicationDate)">
      <range
       minValue="1990"
       maxValue="2000"/>
    </rangeFacetField>
  </rangeFacetFields>
  <sort>
    <sortField
     fieldName="PublicationDate"
     sortOrder="desc"/>
  </sort>
</query>

Example - A query object in JSON format

"query":{
  "queryString":"s.fvgf%3A1=ContentType%2Cor%2CBook%2CJournal+Article&s.hs=%3Ch%3E&s.ho=true&s.fq=Title%3Arain&s.sort=PublicationDate%3Adesc&s.rff=PublicationDate%2C1990%3A2000&s.ps=10&s.debug=false&s.dym=true&s.pn=1&s.rf=PublicationDate%2C1990%3A2000&s.ff=ContentType%2Cor%2C1%2C1&s.hl=true&s.q=forests&s.he=%3C%2Fh%3E&s.fvf=ContentType%2CJournal+Article%2Cfalse",
  "pageNumber":1,
  "pageSize":10,
  "isHighlightingEnabled":true,
  "highlightStartDelimiter":"<h>",
  "highlightEndDelimiter":"</h>",
  "isDidYouMeanEnabled":true,
  "isDebugEnabled":false,
  "isHoldingsOnlyEnabled":true,
  "textQueries":[
    {
      "textQuery":"forests",
      "removeCommand":"removeTextQuery(forests)"
    }
  ],
  "textFilters":[
    {
      "textFilter":"Title:rain",
      "removeCommand":"removeTextFilter(Title:rain)"
    }
  ],
  "rangeFilters":[
    {
      "fieldName":"PublicationDate",
      "range":{
        "minValue":"1990",
        "maxValue":"2000"
      },
      "removeCommand":"removeRangeFilter(PublicationDate,1990:2000)"
    }
  ],
  "facetValueFilters":[
    {
      "fieldName":"ContentType",
      "value":"Journal Article",
      "isNegated":false,
      "removeCommand":"removeFacetValueFilter(ContentType,Journal Article)",
      "negateCommand":"negateFacetValueFilter(ContentType,Journal Article)"
    }
  ],
  "facetValueGroupFilters":[
    {
      "tag":"1",
      "fieldName":"ContentType",
      "combineMode":"or",
      "removeCommand":"removeFacetValueGroupFilter(1)",
      "values":[
        {
          "value":"Book",
          "removeCommand":"removeFacetValueGroupFilter(1,Book)"
        },
        {
          "value":"Journal Article",
          "removeCommand":"removeFacetValueGroupFilter(1,Journal Article)"
        }
      ]
    }
  ],
  "facetFields":[
    {
      "fieldName":"ContentType",
      "combineMode":"or",
      "pageNumber":1,
      "pageSize":1,
      "removeCommand":"removeFacetField(ContentType)"
    }
  ],
  "rangeFacetFields":[
    {
      "fieldName":"PublicationDate",
      "removeCommand":"removeFacetField(PublicationDate)",
      "ranges":[
        {
          "minValue":"1990",
          "maxValue":"2000"
        }
      ]
    }
  ],
  "sort":[
    {
      "fieldName":"PublicationDate",
      "sortOrder":"desc"
    }
  ]
}

Range Facet Fields Response Field

The rangeFacetFields field will be populated if if any range facet field counts were requested in the query. Each rangeFacetField contains the following 4 fields:

  • fieldName - the name of the field being faceted on
  • displayName - the human friendly name of the field being faceted on
  • removeCommand - command to remove this range facet field from the list of requested range facet fields
  • counts - list of the rangeFacetCount items for the individual ranges

Each rangeFacetCount contains the following 4 fields:

  • count - the document count
  • isApplied - whether or not there is a range filter already applied for this range
  • applyCommand - available if not isApplied - the command to apply a range filter for this range
  • removeCommand - available if isApplied - the command to remove the range filter for this range
  • range - the range being counted - contains a minValue and maxValue

The counts field is the only list on rangeFacetField, so there is no nested element for it.

Example - A rangeFacetFields element in XML format

<rangeFacetFields>
  <rangeFacetField
   fieldName="PublicationDate_dt"
   displayName="PublicationDate"
   removeCommand="removeFacetField(PublicationDate)">
    <rangeFacetCount
     count="44512"
     isApplied="true"
     removeCommand="removeRangeFilter(PublicationDate,1981:1990)">
      <range
       minValue="1981"
       maxValue="1990"/>
    </rangeFacetCount>
    <rangeFacetCount
     count="71826"
     isApplied="false"
     applyCommand="addRangeFilter(PublicationDate,1991:2000)">
      <range
       minValue="1991"
       maxValue="2000"/>
    </rangeFacetCount>
  </rangeFacetField>
</rangeFacetFields>

Example - A rangeFacetFields object in JSON format

"rangeFacetFields":[
  {
    "fieldName":"PublicationDate_dt",
    "displayName":"PublicationDate",
    "removeCommand":"removeFacetField(PublicationDate)",
    "counts":[
      {
        "range":{
          "minValue":"1981",
          "maxValue":"1990"
        },
        "count":45763,
        "isApplied":true,
        "removeCommand":"removeRangeFilter(PublicationDate,1981:1990)"
      },
      {
        "range":{
          "minValue":"1991",
          "maxValue":"2000"
        },
        "count":73459,
        "isApplied":false,
        "applyCommand":"addRangeFilter(PublicationDate,1991:2000)"
      }
    ]
  }
]

Recommendation Lists Response Field

The recommendationLists field will be populated if the query is eligible for database recommendations or best bets.

Database Recommendations

Each database recommendation contains the following three fields:
  • title - the database title
  • description - the brief description of the database
  • link - the URL with the library proxy embedded to the database

Example - A recommendationLists element in XML format

<recommendationLists>
  <recommendationList type="database">
    <recommendation title="CINAHL with Full Text"
        description="The Cumulative Index to Nursing and Allied Health Literature"
        link="http://proxy.myinstitution.edu/login?URL=http://search.ebscohost.com/login.aspx?authtype=ip,uid&amp;profile=ehost"/>
  </recommendationList>
</recommendationLists>

Best Bets

Each best bet contains the following three fields:
  • title - the best bet title
  • description - the best bet message
  • link - the URL to a web page with more details

Example - A recommendationLists element in XML format

<recommendationLists>
  <recommendationList type="bestBet">
    <recommendation icon="null" title="Library Hours" description="&lt;p&gt;Sun: 7am - 10pm &amp;nbsp; &amp;nbsp; Thu: 7am - 10pm&lt;/p&gt;&#xd;
&lt;p&gt;Mon: 7am - 10pm &amp;nbsp; &amp;nbsp; Fri: 7am - 8pm&lt;/p&gt;&#xd;
&lt;p&gt;Tue: 7am - 10pm &amp;nbsp; &amp;nbsp; Sat: 10am - 6pm&lt;/p&gt;&#xd;
&lt;p&gt;Wed: 7am - 10pm&lt;/p&gt;" link=""/>

  </recommendationList>
</recommendationLists>

Tokens

Overview

Tokens are any query parameters that are not Summon-specific query parameters. Tokens can be used to replace all, or part, of Summon query parameter values or command arguments. One purpose of tokens is to make it simple to write query proxies. Query proxies can allow end-user-facing apps to have arbitrary query parameters, which can make URLs look neater in some instances. To specify a token to be replaced, use the notation ${tokenName} in any Summon query parameter value, or command argument.

Example - A query proxy for an author/title book search page

Query string as it looks on the proxy page:

  author=Jonathan+Swift&title=Gulliver's+Travels

Query string in Summon format:

  s.cmd=setSearchTerm(Author,Jonathan+Swift)+addSearchTerm(Title,Gulliver's+Travels)+addFacetValueFilters(ContentType,"Book")

Proxy simply appends the following string to the original query string:

  s.cmd=setTextQuery(Author\:\(${author}\))+addTextQuery(Title\:\(${title}\))+addFacetValueFilter(ContentType,Book)

Summon receives the following query:

  author=Jonathan+Swift&title=Gulliver's+Travels&s.cmd=setTextQuery(Author\:\(${author}\))+addTextQuery(Title\:\(${title}\))+addFacetValueFilters(ContentType,Book)

Try It




Health Check Service

Overview

The Summon Search API contains a service for capturing the health status of the Search cluster. This provides a way to get the immediate status of the search system without pinging the Search API directly.


URL

The URL for the Health Check Service is http://api.summon.serialssolutions.com/2.0.0/search/ping


Headers

Because the Health Check Service is apart of the Search API, the authentication headers will be required with each call to the Health Check Service

Output Formats

The output of this service provides the same options available configurable in the authentication headers: XML and JSON.

Example - A basic XML Availability API response

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>available</status>
</response>

Example - A basic JSON Availability API response

{
    "status": "available"
}