OverDrive Developers

Download API

Welcome to the new and improved Download API. We've made it far easier to supply the query parameters. If you've already integrated the download API into your product and need the original documentation, you can find it here. We'll continue to support the prior query parameters, but recommend that you switch to this updated version (when possible).

The Download API allows you to GET a contentLink, which requests a title from our (or our outside provider's) fulfillment servers. Each format, like periodicals-nook or ebook-adobe, has a contentLink that works a little differently.

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.

Getting a contentLink to download a title

Make a GET request to the downloadLink endpoint with the desired title's reserve ID. The call to this endpoint must be made dynamically after a user clicks the download button from your website or app because of the contentLink 60-second timeout and single-use restrictions. If your website or app renders the contentLink as a direct, clickable link, it's likely that the link will expire by the time a user actually clicks on it.

Note: If a contentLink isn't fulfilled within the 60-second time limit, a new request must be made for a fresh contentLink.

Send a GET request to the downloadLink endpoint, using the provided linkTemplate from the Checkouts API response for the title you're trying to download. Here's an example of how it'll look:

https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorurl={errorurl}&successurl={successurl}

Note: At an OverDrive website, we automatically filter out formats that aren't compatible with the device that's being used to access the site (based on user agent). This way, users don't see the formats they can't get with the device they're using right then. If you'd like a similar feature in place, it's something you'll have to develop independently into your app or website.

The {errorurl} parameter requires you to supply a base error page URL. In our example GET below, we replaced the {errorurl} value with https://www.yourwebpage.com/errorpage.htm. If there is a fulfillment error when processing your GET request, the error code will be returned and appended to your supplied error page URL using the following query string parameters:

  • ErrorCode: An OverDrive-specific error code.
  • ErrorDescription: A basic description of the error.
  • ErrorDetails: A more detailed description of the error. You  may want to consider logging this information rather than displaying it to end users.
  • reserveId: OverDrive streaming titles will return this as well to identify which title encountered the error.
  • read_error: An error code specific to OverDrive Read and OverDrive Listen.

The {successurl} parameter requires you to supply a page URL, the location where a user will be sent after successful fulfillment for certain formats. You'll only need a successurl for formats that require it, which right now only includes periodicals-nook.

Note: All query string parameters you add to the downloadLink template must be URL encoded.

To GET a contentLink, the format you're requesting must be locked in (unless it's a format that's always available, like ebook-overdrive or audiobook-overdrive). Below, you'll find a sample downloadLink GET request with a completed downloadLink template.

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm
User-Agent: {Your application}
Authorization: Bearer {OAuth patron access token}
Host: patron.api.overdrive.com
Connection: Keep-Alive

A successful response provides the contentLink:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 546
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Fri, 27 Sep 2013 13:52:22 GMT
Expires: -1

{
    "reserveId": "FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6",
    "formatType": "audiobook-mp3",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/FA87AB78-BC1A-43EA-A81B-05AF55F6F6B6/formats/audiobook-mp3/downloadlink?errorurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm",
            "type": "application/vnd.overdrive.content.api+json"
        },
        "contentLink": {
            "href": "https://ofs.contentreserve.com/bin/OFSGatewayModule.dll/Dracula.odm?RetailerID=odapilib&Expires=1380293542&Token=9736c5b1-69f7-4d50-809b-308c3a20b0ac&Signature=23HFZzxZqRUi7bAHXb0B0HJrWOY=",
            "type": "application/x-od-media"
        }
    }
}

You can then use the contentLink to download the title. As we mentioned earlier, the contentLink for each format works a little differently:

  • For Adobe EPUBs: the contentLink delivers an ACSM file that opens in Adobe Digital Editions or OverDrive's mobile app.
  • OverDrive Read, OverDrive Listen, MediaDo Reader, and streaming videos: the contentLink opens the title in its in-browser reader or player.
  • For MP3 audiobooks: the contentLink delivers an ODM file that opens in OverDrive's desktop app (for Windows or Mac) or OverDrive's mobile app.
  • NOOK periodicals: the contentLink sends you to Barnes & Noble to get the latest issue of the periodical. Successful fulfillment means that the periodical was sent the user's NOOK (BN.com) account, and the user was returned to the successurl provided. That user can then access their periodical in a supported NOOK reading app.

What to do after NOOK periodical fulfillment

When you get a periodical from an OverDrive website, we automatically remove it from a user's bookshelf to free up space to borrow other titles. Periodicals don't work the same way as other formats because the fulfillment is handled by Barnes & Noble, and NOOK periodicals aren't borrowed in the traditional sense (like other formats). Once a user gets a NOOK periodical, the fulfillment counts against the total circulation cap for that issue of the periodical. This help article describes the user experience on an OverDrive website.

Once fulfilled, the user will never need to return the periodical (it's theirs to keep), and it will stay in their NOOK (BN.com) account. After successful fulfillment, you may want to make a return request so the periodical doesn't show up on the user's bookshelf (when you make a GET call for user checkouts). You may also want to prompt them to visit their NOOK reading app to read the periodical.