availability
Overview
The availability service returns item availability info for a given ISBN in the NCSU Libraries catalog. If the identifier is not found, or is not currently available, the service uses OCLC's xISBN service to locate a related catalog item that is currently available.
GET Request Parameters
| Parameter | Value | Description |
|---|---|---|
| service | Enumerated string (required) | Name of desired CatalogWS service. |
| isbn | String (required) | Identifier for item availability lookup. |
| output | Enumerated string (optional), omit for default "xml" |
Defines the output format of the response. Accepted values: "xml", "json". |
Example Request
Implementation Notes
- You must specify a User-Agent in the HTTP headers of your CatalogWS request, otherwise the request will be denied. For example, if you are using the cURL functions in PHP to make requests, you can specify the User-Agent by adding this line to your code:
curl_setopt($ch, CURLOPT_USERAGENT, "My Application Name");
Example Responses
- Requested ISBN with single copy currently available
- Requested ISBN has multiple copies currently available
- Requested ISBN has no copies available; alternate ISBN currently available
- Requested ISBN unknown; alternate ISBN has availability
Elements
<item>
A non-repeating element that contains availability information for the item identified by the requested ISBN.
<isbn>
The ISBN of the item the catalog availability service was performed on.
<totalAvailable>
The total number of copies of this item held by NCSU Libraries that are currently available for checkout, available online or available for in-library use. <totalAvailable> is returned for all catalog availability service requests. For items with at least one copy currently available, this value is an integer greater than zero. For items with no copies currently available, this value is zero (0). For requests with unknown or invalid ISBNs, this value is negative one (-1).
<totalUnavailable>
The total number of copies of this item held by NCSU Libraries that are not currently available for use due to checkouts, holds or other unavailability conditions. For items with at least one copy currently unavailable, this value is an integer greater than zero. For items with all copies currently available, this value is zero. The sum of the values of <totalAvailable> and <totalUnavailable> is the total number of NCSU Libraries catalog holdings for this item.
<availableLibraryName>
The name of a library location where at least one copy of this item currently available. This is a repeating element if the item is currently available at more than one library. If no libraries have current availability, this element does not display.
<unavailableLibraryName>
The name of a library location where at least one copy of this item is currently unavailable. This is a repeating element if the items is currently unavailable at more than one library. If no libraries have an unavailable copy of the item, this element is not returned in the request response. The set of library names included in all <availableLibraryName> and <unavailableLibraryName> elements is the full list of NCSU Libraries library locations holding this item.
<catalogLink>
URL for linking to the NCSU Libraries catalog representation for this item. For requests with unknown or invalid ISBNs, this is a URL linking to the NCSU Libraries catalog search homepage.
<altItem>
A non-repeating element included in the response when the primary ISBN request returns zero (or less) total availability for the item (probably because all copies are "checked out" or because the ISBN is unknown). The alternate ISBN is derived by querying the xISBN service using the primary ISBN as input. The alternate ISBN returned by the catalog availability service is the first xISBN result that is currently available in the NCSU Libraries catalog. The xISBN service ranks ISBN by the most widely held by OCLC member libraries. All <altItem> subelements behave identically to <item> subelements.
Availability Definition
An item is considered "available" (i.e. <totalAvailability> greater than zero) if at least one copy of the item has one of the following catalog availability statuses:
- Available for checkout
- Available for in-library use only
- On reserve