API Reference Guide

Here you'll find a simple reference guide that will help you use OverDrive APIs and understand how they work.

Common terms

• Access token: A string that allows access to the OverDrive APIs when passed as part of the "Authentication" header.
• Advantage accounts: Products (titles) that have been purchased to supplement a library's digital collection. These add to whatever titles libraries have access to through their base consortium collection. You can use "advantageAccount" hypermedia links from the Library Account API to access Advantage-title-only collections, or complete library collections that include both Advantage and base consortium titles.
• Authorization header: A request header used to send authentication credentials.
• Availability: The status of a library title. Using the Availability API, you can see whether or not a title is available, how many copies a library owns, how many are on hold, and how many are checked out.
• Base consortium: The consortium collection of products (titles) available to a library excluding Advantage titles.
• Basic authentication: HTTP authentication allowing a client to provide their username and password when making a request. The user name is appended with a colon and attached to the password. The resulting Base64 encoded string is sent with the HTTP request in the HTTP Authorization header.
• Circulation APIs: These APIs are designed to allow you to circulate content from an OverDrive digital collection. You can borrow and place holds on titles, see what a specific user has borrowed or placed on hold, and get download links for content that a user has borrowed.
• Client authentication: This authentication level gives you access to our Discovery APIs. You don't need to know your users' OverDrive digital collection credentials to utilize our Discovery APIs through Client Authentication.
• Client key: A value passed as part of the OAuth 2.0 Client Credentials Grant Type that identifies the client requesting access. Think of it as a complex username that we generate for you.
• Client secret: A value passed as part of the OAuth 2.0 Client Credentials Grant Type that is bound to a specific client key. Think of it as a complex password that we generate for you.
• CrossRefId: A numeric identifier that allows you to create a permanent link to a title in a library collection or on overdrive.com. Also referred to as titleId.
• Discovery APIs: Discovery APIs are designed to allow your users to browse and explore OverDrive digital collections. You can search for titles, check availability, and get details on specific titles.
• Endpoint: The entry point for a service. In the case of the OverDrive APIs, each endpoint is a URL.
• Forwarded user's IP address: The IP address of the end user who is accessing an API through your application. Please forward this value to us using the "X-Forwarded-For" header unless your app runs directly on an end user's device.
• HTTP header:  Key/value pairs passed as part of a request or response. Standard header fields are defined as part of the HTTP protocol.
• Hypermedia link: A URL included in an API response which allows you navigate to another related API resource. These related resources are labeled with a "rel" identifier.
• JSON (JavaScript Object Notation): An open standard for transmitting structured data over the internet. It is human-readable, and is generally more compact than XML.
• Library account: A library's digital collection of products (titles). The Library Account API is used to get the information you need to access the other APIs for a given library.
• Metadata: Short for "Product Metadata," this refers to the information we use to describe a particular title or product.
• OAuth: An open standard for secure, web-based authorization. We are using OAuth 2.0.
• Pagination: We use this to separate a large set of results into smaller chunks (pages) which can be retrieved using separate requests. Hypermedia links are used to page (or move) through these results.
• Patron authentication: This authentication level gives your users access to OverDrive digital collections through our Discovery and Circulation APIs. For this level, you'll need access to your users' OverDrive digital collection login credentials.
• Product: An individual title (like an ebook or audiobook).
• Products link: A URL pointing to an endpoint that lists all of the available products in a collection. This is the base for the Search API.
• Query parameter:  A key/value pair passed on the URL as part of a full query string. These parameters are a standard way to pass values as part of an GET request.
• Rel (Relationship): An identifier used to define the relationship between a hypermedia link and the resource you're currently accessing. The same "rel" should always link to the same kind of resource, regardless of where the link is found. So, "metadata" will always link to detailed metadata for a specific product based on the context of the link.
• REST: A style of Web API that emphasizes defining "resources" and interacting with them via standard HTTP verbs (GET, PUT, POST, DEL, etc.).
• Search: Built on the Products link, our Search API utilizes a URL query string to filter and organize the products (titles) available in a collection. You can use this to get a response listing titles that match specific criteria.
• User agent: This is a string value passed in the User-Agent header that identifies the web browser or app accessing an online resource.
• Web API (Application Programming Interface): A set of request messages with a clearly defined response structure. Ours are designed to access digital media collections for libraries and retailers.

OverDrive Formats

Each format has a unique identifier which is included in any API response that references title format. Identifiers can be passed to the Search API to filter results.

*The column denotes formats that need to be locked in before you can access the title. Anything marked as "No" is always available during the user's lending period (even if another format is locked in for that title).

Access the Library Account API to see a list of formats available for a specific digital collection. Not all digital collections include every OverDrive format.

Understanding digital formats

Here are some OverDrive help articles about:

• Audiobook formats
• Ebook formats

Best practices and helpful information

Below you'll find some points that will help you use our APIs effectively.

• You can request a website ID using our support form.
• Do not rely on every field being present in each API response.  Most fields in the Discovery endpoints are nullable and may not be included in the responses.
• It's possible to own a title, but not have access to the formats for that title.
• It's possible to get metadata on a title that isn't a part of the collection queried. Always check the isOwnedByCollection field to make sure the collection you're looking at owns the title.
• Always search by lastUpdateTime if you want the most up-to-date information.
• You can save yourself some calls by storing the library (and Advantage) account collection tokens, but don't save them indefinitely. Accounts can change, so you should probably only store these tokens for a few days or weeks.
• Do not store patron collection tokens indefinitely because they can change. We recommend getting a fresh token for each patron session.
• Fields can be added to responses at any time, but we won't remove fields from a response without changing the version number of our APIs.
• Patron authorization calls can take up to 20 seconds when waiting on a response from the ILS used for authentication.
• When building your site or app, provide access to samples of the titles you own (which you can get from the Metadata response).
• When building your site or app, use our logos (provided here). Users look for our brand, which helps to let them know that they might need to download the OverDrive app or Adobe Digital Editions.
• If a library's collection includes preorder titles, you'll see them in the Metadata and Search APIs and users will be able to place holds on them. But, they will be unavailable for checkout until their onSaleDate (in the Metadata response).

Lending models

The publishers determine how digital content circulates (i.e., the lending model). Currently, there are four different lending models for OverDrive's digital content: One Copy/One User, Metered Access (by time or checkouts), Cost Per Circ (CPC), and Simultaneous Use.

One Copy/One User

One Copy/One User titles can be checked out by one person at a time, and they never expire from your library’s collection.

What does that mean in the OverDrive APIs?

Because One Copy/One User titles have a one-to-one ratio of book to user, there will be a waiting list (Holds API) for unavailable titles or the option to borrow it if there's an available copy (Checkouts API), like in a library's physical collection. In the Library Availability API, One Copy/One User titles appear as availabilityType = "Normal" because there are no special cases or oddities for the lending model.

Metered Access

Metered Access titles can be checked out by one person at a time, and they expire from your library collection after a determined period. Some Metered Access titles are metered by time (e.g., they expire after 12 months), some are metered by checkouts or "licenses" (e.g., they expire after 26 checkouts), and some are metered by both (e.g., they expire after the earlier of two years or 52 checkouts).

OverDrive library websites don't display the number of remaining checkouts or remaining time for Metered Access titles. This is a hidden number that libraries manage. That way, they can keep tabs on how many licenses are left for a particular title and quickly replenish them, for example.

What does that mean in the OverDrive APIs?

Metered Access titles look identical to One Copy/One User titles in OverDrive's APIs. There are no special parameters that set them apart, except that, because they can expire from a library's collection (based on time or checkouts), they may become unavailable unexpectedly.

Cost Per Circ

With the Cost Per Circ (CPC) lending model, libraries only pay when their end users borrow CPC titles.

When a library adds CPC titles to their collection, they set a monthly budget for each format (ebook and audiobook). They can also limit the number of CPC titles each individual user can borrow per format each month. CPC titles can be borrowed simultaneously by an unlimited number of people, until the monthly budget runs out or until individual users reach their monthly checkout limit.

What does that mean in the OverDrive APIs?

Cost Per Circ titles look identical to One Copy/One User titles in OverDrive's APIs. The only difference is that they will always show one owned copy, and they will never become unavailable unless the library's monthly budget runs out.

Simultaneous Use

Simultaneous Use titles can be checked out by unlimited people simultaneously, and they expire from a libraries collection after a determined period (for example, after one year).

What does that mean in the OverDrive APIs?

Simultaneous Use titles show up differently in the Library Availability API.

Common HTTP response codes

Below you'll find a list of the most common response codes returned by our APIs:

• 200 OK:  This means everything is just fine.
• 201 Created: This means you've made a successful POST to checkout, lock in a format, or place a hold.
• 204 No Content: This means you've made a successful DELETE to remove a hold or return a title.
• 400 Bad Request:  This covers a range of errors which include detailed error messages.
• 401 Unauthorized:  A user token has expired, is invalid, or attempted to access an endpoint to which it does not have access.
• 404 Not Found:  The item requested was not found, or the URL used to make the call was invalid.
• 500 Internal Server Error:  This means something went wrong on our end.  Please send us the response you get so we can figure out what happened.
• 502 Bad Gateway: This error is given when the wrong protocol is used (HTTP vs HTTPS).
• 503 Service Unavailable:  We're likely experiencing some temporary down-time.  Please let us know when you experienced the trouble and what request you were making.

How to handle Error Response Codes

When you get certain response codes in the response header, you also get a JSON response that includes details about what happened. That JSON response includes a token that we can use to track down what went wrong.

Here's what an error response looks like

{
    "errorCode": "NotFound",
    "message":"An unexpected error has occurred.",
    "token":"b31e17ef-608f-442f-92f1-d0c883673f5a"
}

Please submit a support request that includes the entire error response, and we'll get back to you as soon as we can.