API Documentation Center

Overview

Summon Architecture Diagram

The Summon API suite provides access to:

Access to the API is available via an authentication key. A key can be obtained from Serials Solutions directly. To learn more about how the API authentication works, visit the Authentication page.


Authentication

Overview

Summon Search API uses an authentication scheme based on secret key verification via an HMAC-SHA1 digest. The API performs both authentication and authorization via the same HTTP Authorization header. Creating an Authorization header for an API request requires an access ID, a paired secret key, a client key, and access to certain elements of the HTTP request being authenticated. To create the Authorization header, specific request elements must be assembled into a string that uniquely identifies the request. This ID string is then turned into a digest using the HMAC-SHA1 algorithm as defined in RFC 2104. The digest is then Base64-encoded according to RFC 2045, and assembled into a header along with the access ID.

When the API server receives a request, the first thing it does is check the x-summon-date header to make sure it is within a reasonable margin of the server time. If the header time is not within one hour of the server time then authentication fails immediately. If the request timestamp is acceptable, then the server goes on to check that Summon authentication is being used in the Authorization header. If Summon authentication is being used, the server extracts the access ID, client key and encoded authentication digest from the Authorization header, and looks up the paired secret key using the access ID. Finally the server performs the same algorithm described in the previous paragraph to produce a test digest, and compares the test digest against the digest provided in the Authorization header. If the two digests are identical, the request is authenticated.

Example - A correctly constructed Search API request

GET /2.0.0/search?s.q=forest&s.ff=ContentType,or,1,15 HTTP/1.1
Host: api.summon.serialssolutions.com
Accept: application/xml
x-summon-date: Tue, 30 Jun 2009 12:10:24 GMT
x-summon-session-id: Jp+vWdRgypOOrJQPdzc86mOWFVo=
Authorization: Summon test;rYiYzRaaZ9/QYpiQFZADqpkgJfM=

Assembling The Identification String

The identification string is made up of the following five components:

  1. Accept header value
  2. x-summon-date header value
  3. Host header value
  4. Path portion of the resource URI
  5. Sorted query string unencoded

ID string components are appended to the ID string with a newline ('\n') character after each component. The last component has a trailing newline character like all of the other components, so the last character in the ID string is always a newline.

The first component in the request ID string is the content type as it appears in the Accept header. This will be either application/xml or application/json.

The second component is the date string as it appears in the x-summon-date header. The date string must conform to RFC 2616. The time represented by the date string must be the current time. The request will fail to authenticate if the timestamp differs too much from the server time.

The third component is the host as it appears in the Host header. The host will have just the host name.

The fourth component is the path. The path is everything in the URI that comes after the host and before the query string.

The final component in the ID string is a concatenated list of query parameters, unencoded, sorted in alphabetical order, and separated by '&'.

Example - Constructing an ID string from a request

The request:
 
  GET /2.0.0/search?s.q=forest&s.ff=ContentType,or,1,15 HTTP/1.1
  Host: api.summon.serialssolutions.com
  Accept: application/xml
  x-summon-date: Tue, 30 Jun 2009 12:10:24 GMT
  x-summon-session-id: Jp+vWdRgypOOrJQPdzc86mOWFVo=
 
The constructed ID string:
 
  "application/xml" + "\n" +
  "Tue, 30 Jun 2009 12:10:24 GMT" + "\n" +
  "api.summon.serialssolutions.com" + "\n" +
  "/2.0.0/search" + "\n" +
  "s.ff=ContentType,or,1,15" + "&" + "s.q=forest" + "\n"

Example - Java code for building an ID string

  private String computeIdString(String acceptType, String date, String host, String path, Map<String, String[]> queryParameters) {
    return appendStrings(acceptType, date, host, path, computeSortedQueryString(queryParameters));
  }

  private String computeSortedQueryString(Map<String, String[]> queryParameters) {
    List<String> parameterStrings = new ArrayList<String>();

    // for each parameter, get its key and values
    for (Map.Entry<String, String[]> entry : queryParameters.entrySet()) {

      // for each value, create a string in the format key=value
      for (String value : entry.getValue()) {
        parameterStrings.add(entry.getKey() + "=" + value);
      }
    }

    // sort the individual parameters
    Collections.sort(parameterStrings);
    StringBuilder queryString = new StringBuilder();

    // append strings together with the '&' character as a delimiter
    for (String parameterString : parameterStrings) {
      queryString.append(parameterString).append("&");
    }

    // remove any final trailing '&'
    if (queryString.length() > 0) {
      queryString.setLength(queryString.length() - 1);
    }
    return queryString.toString();
  }

  // append the strings together with '\n' as a delimiter
  public static String appendStrings(String... strings) {
    StringBuilder stringBuilder = new StringBuilder();
    for (String string : strings) {
      stringBuilder.append(string).append("\n");
    }
    return stringBuilder.toString();
  }

Computing the Digest

The digest is computed using the HMAC-SHA1 algorithm as defined in RFC 2104. Then it is encoded using Base64 encoding as defined in RFC 2045. The ID string must be UTF-8 encoded.

Example - Building a digest from an ID string

The constructed ID string:
 
  "application/xml" + "\n" +
  "Tue, 30 Jun 2009 12:10:24 GMT" + "\n" +
  "api.summon.serialssolutions.com" + "\n" +
  "/2.0.0/search" + "\n" +
  "s.ff=ContentType,or,1,15" + "&" + "s.q=forest" + "\n"
 
Hypothetical secret key:
 
  ed2ee2e0-65c1-11de-8a39-0800200c9a66
 
Computed digest:
 
  3a4+j0Wrrx6LF8X4iwOLDetVOu4=

Example - Java code for building a digest from an ID string

public static String buildDigest(String key, String idString) throws SignatureException {
  try {
    String algorithm = "HmacSHA1";
    Charset charset = Charset.forName("utf-8");
    SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), algorithm);
    Mac mac = Mac.getInstance(algorithm);
    mac.init(signingKey);
    return new String(Base64.encodeBase64(mac.doFinal(idString.getBytes(charset))), charset);
  } catch (Exception e) {
    throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
  }
}

The Base64 class used in the above code is from Apache Commons.


Assembling the Authorization Header

The Authorization header is made up of the following three parts:

Summon comes first followed by a space. Then the access ID followed by a semicolon and no space. The HMAC-SHA1 digest comes last.

Example - Building an Authorization header

Access ID:
 
  test
 
HMAC-SHA1 Digest:
 
  rYiYzRaaZ9/QYpiQFZADqpkgJfM=
 
Formatted as an Authorization header string:
 
  Summon test;rYiYzRaaZ9/QYpiQFZADqpkgJfM=

If a given access ID has access to multiple client keys then an additional client key component must be added to the Authorization header. The client key comes after the access ID, and before the HMAC-SHA1 digest. Like the access ID, it is separated by a semicolon and no space.

Example - Building an Authorization header with a client key

Access ID:
 
  test
 
HMAC-SHA1 Digest:
 
  rYiYzRaaZ9/QYpiQFZADqpkgJfM=
 
Formatted as an Authorization header string:
 
  Summon test;rYiYzRaaZ9/QYpiQFZADqpkgJfM=

Availability API

Overview

The Summon Availability API is a service that allows retrieval of catalog item availability statuses. The service allows batch requests for efficiency. This means only one service call is necessary for a page containing multiple catalog items. The Availability API is not an authenticated service. The response format is available in three flavors: XML, JSON and streaming JSON. Since availability status calls can take a relatively long time, the streaming JSON format allows availability statuses to appear on the page as soon as they are retrieved, even if there are still other statuses being retrieved. The combination of batch requests with streaming responses allows for a fairly responsive feel to the UI while only tying up one valuable browser thread.


URL

The base URL for the Availability API is http://api.summon.serialssolutions.com/availability/<client_key> where <client_key> is a valid Serials Solutions client key. The Availability API will return availability statuses for the catalog items owned by the client identified by the given client key.


Headers

The Availability API honors two specific HTTP headers, in addition to the standard required HTTP headers such as Host, and Date. The headers that impact the Availability API are the following:


Parameters

The Availability API accepts one parameter: s.id. There maybe one or more instances of the s.id parameter. Each parameter may contain one availability ID. The availability IDs may be retrieved from the availabilityId field in the documents in a Search API response.

Example - An Availability API query with parameters

http://api.summon.serialssolutions.com/availability/DL5IE4FY9I?s.id=100&s.id=200&s.id=300

Output Formats

The response contains a list of availability items corresponding to the s.id parameters given. An availability item may have multiple availability statuses if there is more than one catalog item for a given availability ID. The basic XML and JSON fromats produce the entire response as a single element or object respectively. The streaming JSON response type returns each availability item as a single JSON object, and each each object is separated by a linefeed ('\n') character.

The availability service aggregates many different availability types, and as a consequence the fields that are returned may vary from library to library. Regardless of the disparate formats, the API will try and provide a "best guess" at what the display string should be for a given catalog item. The "best guess" will appear in the displayString field. If the displayString is not present for a given catalog item, then it is probably best do display a link to the catalog directly to find the item status that way. The other fields that that the Availability API returns include:

If the displayString fails to satisfy the requirements of a particular UI, the other fields may be used to algorithmically generate a custom availability display string. If you choose this option keep in mind that these fields are not guaranteed to appear in all availability items, and the exact content of each field varies from library to library.

Example - A basic XML Availability API response

<?xml version="1.0" encoding="UTF-8"?>
<response
 version="1.1.0"
 sessionId="a83cc71f-4d86-4812-913c-b82952642d60"
 totalRequestTime="0">
  <availabilityItems>
    <availabilities
     id="10563933">
      <availability
       displayString="AVAILABLE, OFF-SITE STORAGE"
       status="available"
       statusMessage="AVAILABLE"
       locationString="OFF-SITE STORAGE"/>
      <availability
       displayString="available, University Library"
       status="available"
       location="University Library"
       callNumber="RC465 .C67 1996"
       locationString="University Library, RC465 .C67 1996"/>
    </availabilities>
    <availabilities
     id="10529706">
      <availability
       displayString="DUE 12-10-2009, University Library"
       status="not available"
       statusMessage="DUE 12-10-2009"
       locationString="University Library"/>
    </availabilities>
    <availabilities
     id="10827389">
      <availability
       displayString="available, OFF-SITE STORAGE"
       status="available"
       location="OFF-SITE STORAGE"/>
    </availabilities>
  </availabilityItems>
</response>

Example - A basic JSON Availability API response

{
  "version":"1.1.0",
  "sessionId":"a83cc71f-4d86-4812-913c-b82952642d60",
  "totalRequestTime":0,
  "availabilityItems":[
    {
      "id":"10563933",
      "availabilities":[
        {
          "displayString":"AVAILABLE, OFF-SITE STORAGE",
          "status":"available",
          "statusMessage":"AVAILABLE",
          "locationString":"OFF-SITE STORAGE"
        },
        {
          "displayString":"available, University Library",
          "status":"available",
          "location":"University Library",
          "callNumber":"RC465 .C67 1996",
          "locationString":"University Library, RC465 .C67 1996"
        }
      ]
    },
    {
      "id":"10529706",
      "availabilities":[
        {
          "displayString":"DUE 12-10-2009, University Library",
          "status":"not available",
          "statusMessage":"DUE 12-10-2009",
          "locationString":"University Library"
        }
      ]
    },
    {
      "id":"10827389",
      "availabilities":[
        {
          "displayString":"available, OFF-SITE STORAGE",
          "status":"available",
          "location":"OFF-SITE STORAGE"
        }
      ]
    }
  ]
}

The streaming JSON format is the content of the availabilityItems array from the basic JSON format, with each object separated by a linefeed ('\n').

Example - A streaming JSON Availability API response

{"id":"10563933","availabilities":[{"displayString":"AVAILABLE, OFF-SITE STORAGE","status":"available","statusMessage":"AVAILABLE","locationString":"OFF-SITE STORAGE"},{"displayString":"available, University Library","status":"available","location":"University Library","callNumber":"RC465 .C67 1996","locationString":"University Library, RC465 .C67 1996"}]}
{"id":"10529706","availabilities":[{"displayString":"DUE 12-10-2009, University Library","status":"not available","statusMessage":"DUE 12-10-2009","locationString":"University Library"}]}
{"id":"10827389","availabilities":[{"displayString":"available, OFF-SITE STORAGE","status":"available","location":"OFF-SITE STORAGE"}]}]}

Code Libraries

Overview

Currently, there are two code libraries available for interfacing with the Summon API. Both are available via GitHub.

Ruby

The Ruby on rails Summon API library summon.rb

PHP

The PHP 5 Summon API library summon.php

Cover Image API

Overview

The Summon Cover Image Resolver is a URL resolver that takes a well known URL format and returns the best cover image based on per-client preferences and subscriptions. The cover image URLs are meant to be used in standard HTML <img> tags, and the resolver uses standard redirects and content types to allow browsers to retrieve the images directly. The Cover Image Resolver is not an authenticated service, but the services that a client subscribes to will determine the images that client can access. The response format may be either image/gif, image/jpeg or image/png. The Cover Image Resolver does not produce images itself, but it aggregates images from several different image providers, depending on user preferences and subscriptions. The quality, size and format of images returned may vary depending on the services a particular client subscribes to.


URL

The URL for the Cover Image Resolver is http://api.summon.serialssolutions.com/2.0.0/image/isbn/<client_key>/<isbn1>_<isbn2>/<size> where <client_key> is a valid Serials Solutions client key, <isbn1> and <isbn2> are valid isbns and <size> is either 'small', 'medium' or 'large'. The Cover Image Resolver will return the best available image chosen from the image services to which the client, identified by the given client key, subscribes.

An image URL for a given Summon document in a Search API response can be retrieved from the thumbnail_s, thumbnail_m or thumbnail_l fields. These fields return the small, medium, and large thumbnails respectively. Not all documents have image URLs.

Example - An image URL for a small thumbnail

http://api.summon.serialssolutions.com/2.0.0/image/isbn/US9EP2KS0P/9781920898625_9781920898458_9781742100784/small

Redirects

To make efficient use of browser side image caching the Cover Image Resolver uses HTTP redirects. If an image is requested using its well known url that contains multiple isbns and a valid image is found for one of the isbns, the response will be an HTTP redirect to the well known url of the single valid isbn. This ensures that individual images will only be cached once, and the cached copy will be used if possible.

Example - An image URL redirect in action

Request an image for a document that has multiple isbns:

    http://api.summon.serialssolutions.com/2.0.0/image/isbn/US9EP2KS0P/9781920898625_9781920898458_9781742100784/small


The Cover Image Resolver determines that there is a valid image for isbn 9781920898625.


The Cover Image Resolver returns a redirect as follows:

    HTTP/1.x 301 Moved Permanently
    Date: Tue, 10 Nov 2009 02:24:46 GMT
    Location: http://api.summon.serialssolutions.com/2.0.0/image/isbn/US9EP2KS0P/9781920898625/small
    Content-Length: 0


The browser can then request the permanently redirected URL which returns:

    HTTP/1.x 200 OK
    Content-Type: image/gif
    Date: Tue, 10 Nov 2009 02:24:46 GMT
    Content-Length: 7073


The redirect and the image are cached, so next time the full three-isbn url, or the short one-isbn URL is requested the image will be pulled from local browser cache.

The no-image Image

In case there is no available image given a set of isbns and client configuration the Cover Image Resolver will return an HTTP redirect to the no-image image. The no-image image is a 1px by 1px transparent gif, so it can be included in the page without an unsightly broken image icon. All no-image images will be redirected to the same URL to make use of caching. In the case of a no-image, the HTTP redirect is temporary instead of permanent.

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.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 - Max Recommendations - Define the maximum number of database recommendations to be presented in the results
  • 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.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.mr=<integer>

A query string may contain only one s.mr 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.mr=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
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"
}

Terms of Use

Summon API Terms of Use

[ Printable Version ]

The Summon™ discovery service (the “Service”) is the property of ProQuest LLC, a Delaware limited liability company, and is licensed through its Serials Solutions business unit (“Serials Solutions”) to subscribing institutions (each a “Customer”) pursuant to a license agreement (“License”). In connection with the Service, Serials Solutions also offers an application programming interface service ("Summon API") to enable users to dynamically connect to the Service. “Summon Data” is all data returned to you via the Summon API from the Service. Your use of the Summon API and the Summon Data constitutes your agreement to be bound by the following terms and conditions ("Terms of Use" or “TOU”) as such terms may be updated from time to time on the Summon website. “Website” refers to the Customer’s website or related applications. The words “you” and “your” (whether or not capitalized) refer to you personally if you are an individual and also to your library, if it is a Customer. Other capitalized terms shall have the meaning defined in the License.

  1. License Grant During the Term, you have a limited, non-exclusive, non-assignable, non-transferable, non-sublicensable, royalty-free license to have access to and use the Summon API, implement access to the Summon API from your Website, and display Summon Data, subject to your compliance with the TOU and the License.
  2. Permitted Uses. You may use and reproduce, without right of distribution, the Summon software code and/or URLs that allow you to create links and receive web search results, only for purposes that support your implementation of the Service on behalf of your library in accordance with its License. Specifically, you may use the Summon API to: (i) enable your Website to obtain Summon Data; (ii) make limited copies of the Summon Data, solely as necessary to display it on your Website; and (iii) host and display limited Summon Data on your Website. You are responsible for your own conduct and content while using the Summon API and for any consequences of this use. All queries to the Summon Data that you provide must be user initiated.
  3. Restrictions. Your license is limited to making direct server calls to the Summon API for purposes of displaying Summon Data to your end users on your Website immediately upon receipt by your servers. Except as expressly permitted in these TOU or in the License, with respect to the Service, the Summon Software, the Summon API or any Summon Data (collectively, “Summon Content”), you shall not, nor shall you permit or authorize any other person to: (i) translate, reverse engineer, disassemble, decompile, make any other attempt to discover, or in any other way reproduce, modify, distribute, the software program source code (except to the extent this is authorized by applicable law notwithstanding this limitation), or harvest metadata from the Summon Content; (ii) remove any proprietary notices, labels or marks from the Summon Content; (iii) sell, sublicense, rent, lend, lease or transfer in any way any portion of the Summon Content; (iv) communicate, redistribute or use the Summon Content to provide services to other libraries or third parties or use or comingle the Summon Content to produce other software products or to make copies of the Summon Content, or for any other commercial use or promotional purpose; (v) copy, store, cache or retain any copies of the Summon Data; (vi) use the Summon Content in any manner that violates any law or regulation, including but not limited to infringing the intellectual property rights of Serials Solutions or any third party, or the rights of any person, including rights of privacy or publicity; (vii) utilize any computer hardware or software designed to defeat any protection device in the Summon Content; (viii) use the Summon API in a manner that constitutes excessive or abusive usage, including to execute denial of service attacks or perform automated searches against Serials Solutions’ systems, including but not limited to automated “bots”, link checkers or other scripts, or otherwise interfere with or disrupt the Service, or servers or networks related to the Service, or disobey any policies of networks related to the Service; (ix) transmit any virus, worm, defect, Trojan horse, or any other item intended to destroy, surreptitiously interfere with, expropriate, or exert unauthorized control over any system or data or to defraud any person; or (x) hide or mask your identity, or the identity of your service, as it uses the Summon API, including by failing to follow any identification conventions listed in the API documentation.
  4. Proprietary Rights. All rights, title and interest in and to the Summon Content, including without limitation documentation, metadata, and any and all new versions, releases, or modifications thereof, are owned by and shall remain with Serials Solutions and are protected by law. This Agreement shall not grant to Customer, you, or any other third party any right of ownership.
  5. Term and Termination; Changes to TOU.
    1. The duration of this license (“Term”) is coterminous with your Customer License, unless earlier terminated as provided herein.
    2. Serials Solutions may terminate your license to use the Summon API and the Summon Data immediately without notice due to your unauthorized use of the Service or failure to comply with the restrictions specified in Section 3.
    3. Upon the termination or expiration of the License for any reason, the Service and your license to use the Summon API and the Summon Data shall terminate immediately.
    4. Serials Solutions routinely adds, changes, improves, or updates the Summon API and Summon Data without notice. Serials Solutions reserves the right to change these TOU from time to time, and you are responsible for regularly reviewing these TOU. Your continued use of the Summon API and/or Summon Data after the effective date of such changes will constitute acceptance of and agreement to any such changes. If you do not agree with the TOU, you may stop using the Summon API and/or Summon Data at any time, without notice to Serials Solutions. Serials Solutions may release subsequent versions of the Summon API and, while commercially reasonable efforts will be made to enable backwards compatibility, this cannot be guaranteed and hence continued use of the Summon API may require you to adapt to the most recent version.
  6. Limited Warranty. EXCEPT AS PROVIDED IN THE LICENSE, THE SUMMON API AND SUMMON DATA ARE PROVIDED “AS IS” AND “AS AVAILABLE” AND SERIALS SOLUTIONS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR DAMAGE FOR DELETED DATA FROM ANY LIBRARY OPAC OR OTHER SYSTEM. WITHOUT LIMITING THE FOREGOING, SERIALS SOLUTIONS DOES NOT WARRANT THAT THE USE OF THE SUMMON API AND SUMMON DATA WILL BE UNINTERRUPTED OR ERROR-FREE OR MAKE ANY WARRANTY AS TO THE AVAILABILITY OF THE SUMMON API AND SUMMON DATA, THE ACCURACY, TIMELINESS OR COMPLETENESS OF THE INFORMATION OR THE RESULTS OF YOUR USE OF THE SUMMON API AND SUMMON DATA. SERIALS SOLUTIONS SPECIFICALLY DISCLAIMS ANY RESPONSIBILITY FOR DETERMINING THE COMPATIBILITY OF THE SUMMON API AND SUMMON DATA WITH ANY HARDWARE OR SOFTWARE NOT SUPPLIED BY SERIALS SOLUTIONS AND MAKES NO WARRANTY WITH RESPECT TO THE OPERATION OF SUCH HARDWARE OR SOFTWARE WITH THE SUMMON API AND SUMMON DATA.
  7. Limitation of Liability. Serials Solutions shall not be liable or deemed in default of the TOU or the License for any failure or delay or interruption in access to the Summon API or any failure of any equipment or telecommunications resulting from any cause or circumstance beyond the reasonable control of Serials Solutions. The License shall state the maximum liability, if any, of Serials Solutions for any claim related to the Summon API. IN NO EVENT SHALL SERIALS SOLUTIONS BE LIABLE TO YOU FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR SPECIAL DAMAGES RELATED TO THE USE OF THE SUMMON API AND SUMMON DATA OR SERIALS SOLUTIONS’ FAILURE TO PERFORM ITS OBLIGATIONS UNDER THE LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, REGARDLESS OF NEGLIGENCE.
  8. Miscellaneous.
    1. These TOU shall be construed according to the laws of the State of Michigan, without application of its conflict of laws provisions.
    2. Serials Solutions and you are independent entities, and nothing in the TOU, or via use of the Service, shall directly or indirectly create a partnership, joint venture, agency, franchise, sales representative, or employment relationship between Serials Solutions and you.
    3. The TOU supersede any previous agreement and, together with the License Agreement, represent the entire agreement between Serials Solutions and you with respect to Service. In the event of any conflict between the TOU and the License Agreement, the License Agreement shall govern and control. If any provision of the TOU is found invalid or unenforceable, the remainder of the TOU shall remain valid and enforceable according to its terms.
    4. Any notices must be sent to ProQuest LLC at: 789 East Eisenhower, P.O. Box 1346, Ann Arbor, MI 48106-1346 USA.