OverDrive Developers

Library Availability API v2

The new and improved Library Availability API (v.2) delivers availability information for a product (title) in a specific library account. 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.

If you need documentation for the previous version of the Library Availability API (v.1), 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. 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 titleId. The reserveId is not case-sensitive.

The availability response:

  • accounts: contains information regarding the number of copies owned/available for each library represented in the collection token.
    • id: -1 refers to a consortium.
    • id: any positive number refers to an Advantage library within the consortium.
    • shared: either "true" or "false." This field describes whether or not a title belonging to the Advantage library is shared with the consortium. This allows users (who do not belong to the Advantage library) to borrow the title. In this case, a consortium will have a higher number of copiesAvailable.
  • available: either "true" or "false." True means a title is available, false means that it's not.
  • availabilityType: describes what lending model the title falls under and any special cases for its circulation.
  • 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.

Example request:

GET https://api.overdrive.com/v2/collections/v1L1BAwAAAA24/products/a5447736-a4b8-4bbd-ada2-a514115b850a/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: Mon, 08 May 2023 14:18:51 GMT
Expires: -1

{
    "reserveId": "a5447736-a4b8-4bbd-ada2-a514115b850a",
    "titleId": 9601778,
    "onSaleDate": "1/1/2101"
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v2/collections/v1L1BvyQAAA2y/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
}

In this response you'll note a few key items:

  • In the request, you passed a reserveId, and in the response, you get back the same reserveId plus the titleId.
  • The onSaleDate shows what 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).
  • There are 17 total copies owned by this library, but none of them are available.
  • There are 2 holds on the title.
  • Its availabilityType is "Normal," meaning it falls under the One Copy/One User (OC/OU) lending model. This type of title circulates similar to physical books at a library, one book per person and the ability to place holds when all copies are checked out.

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.

Shared titles

The "shared" feature allows an Advantage library (who has purchased additional copies of a title) to give members of the consortium (who don't belong to the Advantage library) 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 of a consortium account who has additional access to a "shared" title:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 463
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Fri, 30 Jun 2017 13:05:06 GMT
Expires: -1

{
    "reserveId": "2731C11C-9899-4F5C-A7D7-012122E6D0CB",
    "titleId": 2144602,
    "links": {
        "self": {
            "href": "http://api.overdrive.com/v2/collections/v1L1BAwAAAA24/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. This means this consortium has access to 4 total copies of the title (found under copiesAvailable).

Simultaneous Use titles

Simultaneous Use titles have an availabilityType of "AlwaysAvailable" and appear with approximately 999,999 copies available within a given collection. This number may be larger if the library owned additional copies of the title before it switched to the Simultaneous Use lending model. Titles under this availabilityType can be borrowed by multiple users at the same and don't require users to place holds.

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

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 445
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Tue, 27 Jun 2017 19:39:29 GMT
Expires: -1

{
    "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 25 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/v1L1BAwAAAA24/availability?products=789876,789916
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, 28 Jun 2017 14:03:12 GMT
Expires: -1

{
    "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/v1L1BvyQAAA2y/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 are 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:

400 BadRequest
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 88
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Thu, 29 Jun 2017 15:08:02 GMT
Expires: -1

{
    "message": "Invalid guid at position: 1",
    "token": "d222ca5c-f78d-4ddf-966c-0327dbe81a9f"
}

If none of the requested titles are found, you'll get:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 189
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Thu, 29 Jun 2017 15:08:15 GMT
Expires: -1

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

Copyright © 2014 OverDrive, Inc. All rights reserved.