OverDrive Developers

Download API (old query parameters)

The Download API allows you to GET a contentLink. This link, in turn, requests a title download from our fulfillment servers.  In the case of Adobe EPUBs, the contentLink delivers an ACSM file that opens in Adobe Digital Editions or OverDrive's mobile app.  For audiobooks, music, and video, the contentLink delivers an ODM file that opens in OverDrive Media Console for Windows or Mac.

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.

Please be aware that the OverDrive Download API cannot filter formats by detecting an end user's device. If you'd like to add format filtering, you'll need to do so within the app you're developing.

Note: contentLinks have a one-time use restriction and are only valid for 60 seconds after one is created. If fulfillment is not completed within that timeframe, a new request must be made for a fresh contentLink.

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 patron 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.

When you send the GET request to the formats endpoint, use the provided linkTemplate from the Checkouts API response for the title you're trying to download. The downloadLink template (example shown below) can be found in the linkTemplates section of a checkouts response.

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

The {errorpageurl} parameter requires you to supply a base error page URL. In our example GET below, we replaced the {errorpageurl} 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 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 then displaying it to end users.

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

Remember, to GET a contentLink, the format you're requesting must be locked in. 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?errorpageurl=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?errorpageurl=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 use the contentLink to download the title. For ODM and ACSM files, fulfillment is not complete until the ODM or ACSM file has been opened.

Getting a contentLink for an OverDrive Read eBook or an OverDrive Listen audiobook

When you make a GET request for an OverDrive Read eBook or an OverDrive Listen audiobook contentLink, you'll need to also provide an authorization page URL. The linkTemplates example below was taken from the formats endpoint of a Checkouts API GET response.

https://patron.api.overdrive.com/v1/patrons/me/checkouts/AF5CAA07-E4D3-4A72-ADE3-644687FEA48E/formats/ebook-overdrive/downloadlink?errorpageurl={errorpageurl}&odreadauthurl={odreadauthurl}

Below is an example GET request with a completed downloadLink template for an OverDrive Read eBook.

Note: You must pass both the errorpageurl and odreadauthurl parameters when requesting a downloadLink for OverDrive Read eBooks and OverDrive Listen audiobooks.  
"https://www.yourwebpage.com/odreadauth?reserveid=[RESERVE_ID]&read_error=[READ_ERROR]" is the odreadauthurl used below:

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/AF5CAA07-E4D3-4A72-ADE3-644687FEA48E/formats/ebook-overdrive/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&odreadauthurl=https%3a%2f%2fwww.yourwebpage.com%2fodreadauth%3Freserveid%3D%5BRESERVE_ID%5D%26read_error%3D%5BREAD_ERROR%5D
User-Agent: {Your application} Authorization: Bearer {OAuth patron access token} Host: patron.api.overdrive.com Connection: Keep-Alive

Here's the response:

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

{
    "reserveId": "AF5CAA07-E4D3-4A72-ADE3-644687FEA48E",
    "formatType": "ebook-overdrive",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/AF5CAA07-E4D3-4A72-ADE3-644687FEA48E/formats/ebook-overdrive/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&odreadauthurl=https%3a%2f%2fwww.yourwebpage.com%2fodreadauth",
"type": "application/vnd.overdrive.content.api+json" }, "contentLink": { "href": "https://ofs.contentreserve.com/bin/OFSGatewayModule.dll/InfernoRobertLangdonSeriesBook049780385537865.epub-sample.overdrive.com?RetailerID=odapilib&Expires=1380299761&Token=6c4aed5e-680e-47ee-abc0-3b2372602452&Signature=Q4EUsgVzVEIG8kIpd6EHE7xkImQ=", "type": "text/html" } } }

The contentLink for an OverDrive Read eBook or an OverDrive Listen audiobook is a direct link to open the title in the user's web browser.

There are a series of error codes associated specifically with OverDrive Read and OverDrive Listen. You can find a list of these errors here, each of which may occur during fulfillment of the OverDrive Read or OverDrive Listen title.

When an error is encountered during OverDrive Read or OverDrive Listen fulfillment, the user will be redirected to the {odreadauthurl} value that you supplied with the contentLink request. The particular OverDrive Read error code that occurred will be substituted into the "read_error=[READ_ERROR]" parameter of the response.

Getting a contentLink for an OverDrive streaming video title

Content links for streaming video work just like OverDrive Read. When you make a GET request for an OverDrive streaming video contentLink, you'll need to also provide an authorization page URL. The linkTemplates example below was taken from the formats endpoint of a Checkouts API GET response.

https://patron.api.overdrive.com/v1/patrons/me/checkouts/AF5CAA07-E4D3-4A72-ADE3-644687FEA48E/formats/video-streaming/downloadlink?errorpageurl={errorpageurl}&streamingauthurl={streamingauthurl}

Below is an example GET request with a completed downloadLink template for a streaming video.

Note: You must pass both the errorpageurl and streamingauthurl parameters when requesting a downloadLink for streaming videos.
"https://www.yourwebpage.com/streamingvideoauth" is the streamingauthurl used below:

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/D296E8B2-3E70-412A-A0CF-79B93CE122CA/formats/video-streaming/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&streamingauthurl=https%3A%2f%2fwww.yourwebpage.com%2fstreamingvideoauth
User-Agent: {Your application} Authorization: {OAuth patron access token} Host: patron.api.overdrive.com Connection: Keep-Alive

Here's the response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 642
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Thu, 06 Mar 2014 14:20:00 GMT
Expires: -1


{
    "reserveId": "D296E8B2-3E70-412A-A0CF-79B93CE122CA",
    "formatType": "video-streaming",
    "links": {
        "self": {
            "href": "https://patron.api.overdrive.com/v1/patrons/me/checkouts/D296E8B2-3E70-412A-A0CF-79B93CE122CA/formats/video-streaming/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&streamingauthurl=https%3A%2f%2fwww.yourwebpage.com%2fstreamingvideoauth",
            "type": "application/vnd.overdrive.circulation.api+json"
        },
        "contentlink": {
            "href": "https://fulfill.contentreserve.com/WorldWar1-8.mp4?RetailerID=odapilib&Expires=1394119201&Token=ede0fdb6-27df-41bb-a8b8-a2e60099d064&Signature=kiUlE3YWqto8gVZglnmVvr044vs=",
            "type": "text/html"
        }
    }
}

The contentLink for a streaming video is a direct link to open the video.

Getting a contentLink for a NOOK periodical

Content links for periodicals have one new requirement. When you make a GET request for an OverDrive periodical contentLink, you'll need to also provide a success page URL. The linkTemplates example below was taken from the formats endpoint of a Checkouts API GET response.

https://patron.api.overdrive.com/v1/patrons/me/checkouts/AF5CAA07-E4D3-4A72-ADE3-644687FEA48E/formats/ebook-periodicals/downloadlink?errorpageurl={errorpageurl}&successurl={successurl}

Below is an example GET request with the using a completed downloadLink template for a periodical.

Note: You must pass both the errorpageurl and successurl parameters when requesting a downloadLink for periodicals.
"https://www.yourwebpage.com/periodicalsuccessurl" is the successurl used below:

GET https://patron.api.overdrive.com/v1/patrons/me/checkouts/D296E8B2-3E70-412A-A0CF-79B93CE122CA/formats/ebook-periodicals/downloadlink?errorpageurl=https%3A%2f%2fwww.yourwebpage.com%2ferrorpage.htm&successurl=https%3A%2f%2fwww.yourwebpage.com%2fperiodicalsuccessurl
User-Agent: {Your application} Authorization: {OAuth patron access token} Host: patron.api.overdrive.com Connection: Keep-Alive

The contentLink for a NOOK periodical is a link to get the latest issue of the periodical through Barnes & Noble. Upon success, the periodical is sent to the user's NOOK (BN.com) account. That user will need to view the periodical in a supported NOOK reading app. The success page URL will return a user to that location after a periodical is successfully fulfilled. 

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.