Library Availability API

The Library Availability API v2 delivers availability information for a product (title) in a specific library or school collection. This includes the number of copies owned, the number of holds on that title, and whether or not it is currently available for checkout.

If you need documentation for the previous version of the Library Availability API (v1), you can find it here.

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration.api.overdrive.com or https://integration-patron.api.overdrive.com.

Using the Library Availability API

The Library Availability API returns availability information on a library or school title and can be accessed with a hypermedia link from the Search API results.

Requests to this API accept either a reserveId or titleId. The reserveId is not case-sensitive.

Resource URL

https://api.overdrive.com/v2/collections/{collectionToken}/products/{reserveId}/availability

Example request

GET https://api.overdrive.com/v2/collections/v1L1BBQ0AAA2_/products/a5447736-a4b8-4bbd-ada2-a514115b850a/availability 
User-Agent: {Your application} 
Authorization: Bearer {OAuth access token} 
Host: api.overdrive.com

Example response

200 OK
Date: Fri, 03 May 2024 20:46:47 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 439
Content-Type: application/json; charset=utf-8

{
    "reserveId": "a5447736-a4b8-4bbd-ada2-a514115b850a",
    "titleId": 9601778,
    "onSaleDate": "1/1/2101",
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v2/collections/v1L1BBQ0AAA2_/products/a5447736-a4b8-4bbd-ada2-a514115b850a/availability",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "accounts": [
        {
            "id": -1,
            "copiesOwned": 17,
            "copiesAvailable": 0
        }
    ],
    "available": false,
    "availabilityType": "Normal",
    "copiesOwned": 17,
    "copiesAvailable": 0,
    "numberOfHolds": 2
}

This response includes:

accounts: shows the number of copies owned/available for each library or school represented in the collection token.
- id:-1 refers to a consortium.
- id:any positive number refers to an Advantage library or school within the consortium.
available: either "true" or "false." When a title is available, it can be checked out by a user.
availabilityType: can be used to differentiate Subscription titles from other lending models. Most titles have an availabilityType of "Normal," while Subscription titles have an availabilityType of "AlwaysAvailable."
copiesOwned: how many total copies there are in the collection.
copiesAvailable: how many copies are available for checkout.
numberOfHolds: how many holds there are on the title.
onSaleDate: the date the title becomes available for users to borrow. This will only be included in the response if the title is a preorder (i.e., the date is in the future).

Note: If you're using an authenticated patron access token, you'll also see actions that allow you to check out the title (using the Checkouts API) or place a hold (using the Holds API).

Shared titles

The "shared" feature allows an Advantage library or school (who has purchased additional copies of a title) to give members of the consortium (who don't belong to the Advantage library/school) access to the title as well. This may mean that a consortium has access to more copies of the title, or it may mean that the consortium only has access to the title because of the Advantage collection.

Example response

200 OK
Date: Fri, 03 May 2024 20:55:53 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 463
Content-Type: application/json; charset=utf-8

{
    "reserveId": "2731C11C-9899-4F5C-A7D7-012122E6D0CB",
    "titleId": 2144602,
    "links": {
        "self": {
            "href": "http://api.overdrive.com/v2/collections/v1L1BBQ0AAA2_/products/2731C11C-9899-4F5C-A7D7-012122E6D0CB/availability",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "accounts": [
        {
            "id": -1,
            "copiesOwned": 3,
            "copiesAvailable": 0
        },
        {
            "id": 121,
            "shared": true,
            "copiesOwned": 1,
            "copiesAvailable": 0
        }
    ],
    "available": false,
    "availabilityType": "Normal",
    "copiesOwned": 4,
    "copiesAvailable": 0,
    "numberOfHolds": 0
}

In this example, the consortium account owns 3 copies of the title (represented as id: -1). The Advantage account (id: 121) owns a single copy and has shared it with the consortium (shared: true). This means this consortium has access to 4 total copies of the title (found under copiesOwned).

Note: In rare instances, an Advantage library or school may share a Cost Per Circ (CPC) title with their consortium. When this happens, more copies may be reflected in the Library Availability API response than are currently available. This is most likely to happen when the consortium account owns the same title in a different lending model (like OC/OU). When all of the consortium's OC/OU copies are borrowed, the CPC copy may still show as available, though it can't be borrowed by consortium users. You may see this API response when this is the case: NoCopiesAvailable_AvailableInCpcForFastLaneMembersOnly. When this happens, we recommend prompting the user to place a hold on the title instead.

Subscription titles

Subscription titles have an availabilityType of "AlwaysAvailable," can be borrowed by unlimited users at the same time, and don't require users to place holds.

In API responses, a Subscription title has approximately 999,999 copies available within a given collection. This number can be larger if the library or school purchased copies of the title in a different lending model before purchasing it as Subscription.

Example response

200 OK
Date: Fri, 03 May 2024 21:00:05 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 443
Content-Type: application/json; charset=utf-8
    
{ 
    "reserveId": "FFCA0F93-7A7C-433A-B271-000B902C635B", 
    "titleId": 2087011, 
    "links": { 
        "self": { 
            "href": "http://api.overdrive.com/v2/collections/v1L1BYwAAAA2Q/products/FFCA0F93-7A7C-433A-B271-000B902C635B/availability", 
            "type": "application/vnd.overdrive.api+json" 
        } 
    }, 
    "accounts": [ 
        { 
            "id": -1, 
            "copiesOwned": 999999, 
            "copiesAvailable": 999999 
        } 
    ], 
    "available": true, 
    "availabilityType": "AlwaysAvailable", 
    "copiesOwned": 999999, 
    "copiesAvailable": 999999, 
    "numberOfHolds": 0 
}

Making a bulk availability call

You can use this endpoint to get the availability of up to 50 titles at once. In the GET request, separate the reserveIds (or titleIds) for each title with commas. Note that reserveIds are not case sensitive, and you cannot have both reserveIds and titleIds in the same bulk request; you must choose one or the other.

Example request

GET https://api.overdrive.com/v2/collections/v1L1BBQ0AAA2_/availability?products=789876,789916 
User-Agent: {Your application} 
Authorization: Bearer {OAuth access token} 
Host: api.overdrive.com

Example response

200 OK
Date: Tue, 07 May 2024 14:32:46 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 660
Content-Type: application/json; charset=utf-8
    
{ 
    "availability": [ 
        { 
            "reserveId": "622708F6-78D7-453A-A7C5-3FE6853F3167", 
            "titleId": 789876, 
            "accounts": [ 
                { 
                    "id": -1, 
                    "copiesOwned": 1, 
                    "copiesAvailable": 1 
                } 
            ], 
            "available": true, 
            "availabilityType": "Normal", 
            "copiesOwned": 1, 
            "copiesAvailable": 1, 
            "numberOfHolds": 0 
        }, 
        { 
            "reserveId": "A79BB485-5A7B-4100-8661-3A4647E70BAF", 
            "titleId": 789916, 
            "accounts": [ 
                { 
                    "id": -1, 
                    "copiesOwned": 1, 
                    "copiesAvailable": 1 
                } 
            ], 
            "available": true, 
            "availabilityType": "Normal", 
            "copiesOwned": 1, 
            "copiesAvailable": 1, 
            "numberOfHolds": 0 
        } 
    ], 
    "totalItems": 2, 
    "links": { 
        "self": { 
            "href": "https://api.overdrive.com/v2/collections/v1L1BBQ0AAA2_/availability?products=95523eba-cc01-40fc-a1c5-85e0b0eb0eae,8D5D5C54-4ED6-4009-8065-5A0CE92C44C0", 
            "type": "application/vnd.overdrive.api+json" 
        } 
    } 
}

If any of the reserveIds or titleIds passed in the request aren't in the collection (or aren't formatted correctly, etc.), then you'll see as many titles as the API can find. For example, if you pass 2 titleIds and only 1 is valid, the response will return the 1 valid title.

If the request is entirely invalid due to formatting issues, you'll get a "400 BadRequest" error:

Example error response

400 BadRequest
Date: Tue, 07 May 2024 15:48:41 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 126
Content-Type: application/json; charset=utf-8
    
{ 
    "errorCode": "InputValidationError",
	"message": "Invalid identifier at index: 0", 
    "token": "d222ca5c-f78d-4ddf-966c-0327dbe81a9f" 
}

If none of the requested titles are found, you'll get a "200 OK" response with zero totalItems:

Example response

200 OK
Date: Tue, 07 May 2024 15:54:40 GMT
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Length: 174
Content-Type: application/json; charset=utf-8

{ 
    "totalItems": 0, 
    "links": { 
        "self": { 
            "href": "http://api.overdrive.com/v2/collections/v1L1BBQ0AAA2_/availability?products=123456789,12345678", 
            "type": "application/vnd.overdrive.api+json" 
        } 
    } 
}