OverDrive Developers

Library Availability API

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

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration-patron.api.overdrive.com. For more information on the integration environment, please see Getting Started.

Using the Library Availability API

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

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

The availability response:

  • collections: contains information regarding the number of copies owned/available/on hold for each library represented in the collection token.
  • available: either "true" or "false." True means a title is available, false means that it's not.
  • 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.
  • availabilityType: describes what lending model the title falls under and any special cases for its circulation.

Example request:

GET https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/products/ebff8d7b-c9a0-4478-a1ed-63b64e8386c5/availability
User-Agent: {Your application}
Authorization: Bearer {OAuth access token}
Host: api.overdrive.com

Example response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 447
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Feb 2016 14:18:51 GMT
Expires: -1
{
    "id": "ebff8d7b-c9a0-4478-a1ed-63b64e8386c5",
    "crossRefId": 1427131,
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/products/ebff8d7b-c9a0-4478-a1ed-63b64e8386c5/availability",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "collections": [
        {
            "id": "Your Public Library",
            "copiesOwned": 5,
            "copiesAvailable": 5,
            "numberOfHolds": 0
        }
    ],
    "available": true,
    "availabilityType": "Normal",
    "copiesOwned": 5,
    "copiesAvailable": 5,
    "numberOfHolds": 0
}

This response shows that there are five total copies of this title in this library's collection. All of them are available for checkout, so there are no holds currently on the title. In this example, the title had an availabilityType with value "Normal" because it falls under the One Copy/One User lending model. This basically means it will always be available to check out or place holds on. For more information about lending models, visit our Reference Guide.

Note: If you're using an authenticated patron access token, you will also see actions that allow you to check out or place a hold on the title via a POST using the Checkouts API.

Simultaneous Use and Cost Per Circ titles are a little different

Simultaneous Use titles will show up with approximately 999,999 copies available within a given collection. This number can be a bit bigger if copies of the title were owned prior to the title switching to the Simultaneous Use lending model.

Here's an example of an availability response for a Simultaneous Use title:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 456
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 16 Dec 2014 14:43:06 GMT
Expires: -1

{
    "id": "c02f9972-631d-483c-a0a3-d6359534851d",
    "crossRefId": 505428,
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v1/collections/v1L1BAwAAAA24/products/C02F9972-631D-483C-A0A3-D6359534851D/availability",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "collections": [
        {
            "id": "Your Public Library",
            "copiesOwned": 999999,
            "copiesAvailable": 999999,
            "numberOfHolds": 0
        }
    ],
    "available": true,
    "availabilityType": "AlwaysAvailable",
    "copiesOwned": 999999,
    "copiesAvailable": 999999,
    "numberOfHolds": 0
}

Note that the availabilityType is "AlwaysAvailable" and the copiesOwned is 999999.

Cost Per Circ (CPC) titles will show up with 500,000 copies available within a given collection, and "LimitedAvailablility" will show up in the response. Because CPC titles are generally limited by budget caps, it's possible that a title under this model will simply become unavailable at some point, and it will fail to fulfill (meaning the Checkouts API won't work if you try to borrow it).

Here's an example of an availability response for a CPC title:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 456
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 16 Dec 2014 14:43:06 GMT
Expires: -1

{
    "id": "CD5304A3-9745-478C-BD02-002F2408D610",
    "crossRefId": 848945,
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v1/collections/v1L1BAwAAAA24/products/CD5304A3-9745-478C-BD02-002F2408D610/availability",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "collections": [
        {
            "id": "Your Public Library",
            "copiesOwned": 500000,
            "copiesAvailable": 499999,
            "numberOfHolds": 0
        }
    ],
    "available": true,
    "availabilityType": "LimitedAvailability",
    "copiesOwned": 500000,
    "copiesAvailable": 499999,
    "numberOfHolds": 0
}

Note that the availabilityType is "LimitedAvailability" and the copiesOwned is 500000.

Preorder titles

Preorder titles appear in the Library Availability response as "0" ownedCopies, "0" copiesAvailable, and available: false.

Here's an example of what a preorder title will look like in a Library Availability response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 449
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Mon, 08 May 2023 13:49:49 GMT
Expires: -1
{
    "id": "a5447736-a4b8-4bbd-ada2-a514115b850a",
    "crossRefId": 9601778,
    "onSaleDate": "1/1/2101",
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v1/collections/v1L1BFQAAAA2x/products/a5447736-a4b8-4bbd-ada2-a514115b850a/availability",
            "type": "application/vnd.overdrive.api+json"
        }
    },
    "collections": [
        {
            "id": "Your Public Library",
            "copiesOwned": 0,
            "copiesAvailable": 0,
            "numberOfHolds": 12
        }
    ],
    "available": false,
    "availabilityType": "Normal",
    "copiesOwned": 0,
    "copiesAvailable": 0,
    "numberOfHolds": 12
}

In this example, the title has also started to accrue holds in anticipation of its release even though it shows as "0" copiesOwned in the response.

Note: On OverDrive library websites, there's a special note for preorder titles to let everyone know that they can place holds but will be unable to borrow the title.

Once the onSaleDate passes, the copiesOwned will be updated and the title will circulate normally.

Making a bulk availability call

This endpoint works best if you'd like to get availability for several titles at once. You can ask for the availability for up to 25 titles at a time by supplying the reserveId or crossRefId for each one.

Example request:

GET https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/availability?products=95523eba-cc01-40fc-a1c5-85e0b0eb0eae%2C193f0269-97f7-4dfd-9e5a-aef9d6a3a010
User-Agent: {Your application}
Authorization: Bearer {OAuth access token}
Host: api.overdrive.com

Example response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 625
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Feb 2016 14:03:12 GMT
Expires: -1

{
    "id": "OverDrive API Integration Library (OH)",
    "availability": [
        { 
            "id": "95523eba-cc01-40fc-a1c5-85e0b0eb0eae",
            "crossRefId": 1181513,
            "accountId": 4425, 
            "available": true, 
            "availabilityType": "Normal", 
            "copiesOwned": 1, 
            "copiesAvailable": 1, 
            "numberOfHolds": 0 
        },
        { 
            "id": "193f0269-97f7-4dfd-9e5a-aef9d6a3a010", 
            "crossRefId": 2050995,
            "accountId": 4425, 
            "available": true, 
            "availabilityType": "Normal", 
            "copiesOwned": 1, 
            "copiesAvailable": 1, 
            "numberOfHolds": 0 
        }
    ],
    "totalItems": 2,
    "links": {
        "self": { 
            "href": "https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/availability?products=95523eba-cc01-40fc-a1c5-85e0b0eb0eae,193f0269-97f7-4dfd-9e5a-aef9d6a3a010", 
            "type": "application/vnd.overdrive.api+json" 
        }
    }
}

If any of the reserveIds or crossRefIds passed in the request aren't in the collection (or aren't formatted correctly, etc.), then you'll see the following response instead:

400 BadRequest
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 83
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Feb 2016 15:00:11 GMT
Expires: -1
{ 
    "message": "Invalid product passed", 
    "token": "165b607f-79eb-4e53-afcf-d6d9b1e81e08" 
}

Copyright © 2014 OverDrive, Inc. All rights reserved.