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: +-&|!(){}[]^"~*?:\. 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