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"}]}]}