OverDrive Developers

Download API v2

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 magazine-overdrive 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}

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.

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, magazines, 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.