Checkouts Report API
The Checkouts Report API gives details about the titles that were borrowed from a library within a time frame you specify. You can see which branch the checkout is from, the date it was borrowed, the user ID that borrowed it (if enabled), and more.
Notes:
- If you'd like user IDs to appear in the API response, you'll need to specify this when requesting API access or contact support to enable them later.
- OverDrive schedules a maintenance window on the first Thursday of every month, from 6:00AM - 8:00AM EST. Please make sure you're not accessing this API during this window.
- Checkout data is only available for the library associated with the API credentials (i.e., client key). There is no way to access data for another library.
- The examples below show our production API URL. If you're using our integration environment, use https://integration-reports.api.overdrive.com/v1/checkouts.
Using the Checkouts Report API
The Checkouts Report API uses GET requests to retrieve checkout data.
Resource URL
https://reports.api.overdrive.com/v1/checkouts?{parameters}Query parameters
| Parameter | Description |
|---|---|
| startDateUtc | Formatted as yyyy-mm-dd or yyyy-MM-ddTHH:mm:ssZ. |
| endDateUtc | Formatted as yyyy-mm-dd or yyyy-MM-ddTHH:mm:ssZ. |
| pageSize | The maximum size of the result set. Defaults to 1000 (the max value) if a value isn't included. See more details under "Pagination" below. |
| websiteId | The digital collection you want to report on, required for some API implementations. If you need to include this parameter, our support team will send your websiteId when they send your client key. |
Example request
GET https://reports.api.overdrive.com/v1/checkouts?startDateUtc=2023-10-01&endDateUtc=2023-10-03&websiteId=100300
User-Agent: {Your application}
Authorization: Bearer {OAuth access token}
Host: api.overdrive.comExample response
200 OK
Date: Wed, 12 Jun 2024 12:46:49 GMT
Vary: Accept-Encoding
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{
"checkouts": [
{
"checkoutId": "100300-6909841-00489",
"branch": "Demo Integration",
"checkoutDateUtc": "10/01/2023 19:08:20",
"lendingPeriodDays": 14,
"borrowedFrom": "Main collection",
"isRenewal": false,
"boughtBy": "Consortium",
"titleId": 105286,
"reserveId": "4aa00d73-8f4b-4652-bcb4-88c175e247d3",
"title": "The Lightning Thief: Percy Jackson and the Olympians: Book 1 (unabridged)",
"edition": "Unabridged",
"creator": "Rick Riordan",
"isbn": "9780739345146",
"language": "{\"LanguageCode\":\"en\",\"Name\":\"English\"}",
"audienceRating": "Juvenile Fiction",
"subjects": [
"Fantasy",
"Juvenile Fiction",
"Juvenile Literature",
"Mythology"
],
"format": "Audiobook",
"publisher": "Books on Tape"
},
{
"checkoutId": "100300-6908187-00473",
"branch": "Demo Integration",
"checkoutDateUtc": "10/01/2023 19:37:46",
"lendingPeriodDays": 21,
"borrowedFrom": "Libby",
"isRenewal": false,
"boughtBy": "Consortium",
"titleId": 25475,
"reserveId": "0d85564b-a4b3-43d5-875d-1df3ca06ae65",
"title": "A Game of Thrones: A Song of Ice and Fire: Book One",
"creator": "George R. R. Martin",
"isbn": "9780553897845",
"language": "{\"LanguageCode\":\"en\",\"Name\":\"English\"}",
"audienceRating": "Adult Fiction",
"subjects": [
"Fantasy",
"Fiction",
"Science Fiction",
"Thriller"
],
"format": "eBook",
"publisher": "Random House Publishing Group"
},
{
"checkoutId": "100300-6908234-00504",
"branch": "Demo Integration",
"checkoutDateUtc": "10/01/2023 19:58:42",
"lendingPeriodDays": 14,
"borrowedFrom": "Libby",
"isRenewal": false,
"boughtBy": "Demo Integration",
"titleId": 784695,
"reserveId": "71538b32-02dc-4570-8aff-9beb039a2267",
"title": "Little Women",
"creator": "Louisa May Alcott",
"isbn": "9781620114568",
"language": "{\"LanguageCode\":\"en\",\"Name\":\"English\"}",
"audienceRating": "Juvenile Fiction",
"subjects": [
"Classic Literature",
"Juvenile Fiction",
"Juvenile Literature"
],
"format": "eBook",
"publisher": "Duke Classics"
}
],
"totalcheckouts": 3
}The request returns a response that includes:
- branch: used to distinguish members of a consortium. For example, each Advantage library might be a different branch.
- checkoutDateUtc: the date (formatted as mm/dd/yyyy) and time when the title was borrowed.
- borrowedFrom: the location where the title was borrowed, such as Libby or the library’s OverDrive website (main collection).
- boughtBy: the library that purchased the title. This could be the consortium or a library branch (such as an Advantage library).
- reserveId and titleId: identifiers for OverDrive titles that you can use in calls for other APIs (like the Library Availability API) to get information about the title.
- Other title metadata: details about the title, such as the author/creator, language, audience, and subjects.
Pagination
The pageSize parameter determines how many titles are returned in a single page. We recommend setting this parameter to the largest size your systems can handle (up to 1000).
If there are multiple pages of results, the response will have a nextPageUrl field. Make a GET request with the URL in this field to go to the next page of results.
202 response code
The 202 response code is returned when the API's load is too heavy to respond right away. This scenario only happens on the first request and does not need to be handled for subsequent calls to the nextPageUrl.
There are a couple ways you can handle this response:
- Wait the number of seconds indicated by the value in the "Retry-After" header, then send the same request again. Note that the data is not guaranteed to be ready after this period, and you may need to retry the request multiple times.
- If your program is run by a task scheduler that automatically restarts failed tasks, treat the 202 response as an error and exit with an error code.
Limitations
Requests to this API are limited in a few ways:
Appointments
To handle the load of serving data to all our partners, your client key will be assigned to one or more daily time windows where you can access this API. If you make requests to this API outside of your assigned window, you'll get a 400 error.
The OverDrive Integration Support team will assign your time windows and send them to you when you're getting set up with this API.
Rate limiting
Rate limits on this API may change based on need. As a best practice, you should only make one request at a time for your client key.
Rate limit errors are generally rare, but if you exceed the rate limits, you'll get a 429 response and should try the request again after a short time.
Historical data restrictions
To prevent excessive system load from re-downloading all historical data, this API can forbid clients from requesting data older than a certain time window.
The OverDrive Integration Support team will discuss this limitation with you when you're getting set up with this API. If you need to obtain all historical data for a library, please contact support. We may be able to send you historical data in a file format.