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