OverDrive Developers

Metadata API

The Metadata API delivers detailed metadata for a specific product, including author, title, genre, synopses, reviews, and more. Remember that not all titles will have data associated with every possible metadata field.

Note: The examples below show our production API URL. If you're using our integration environment, use https://integration.api.overdrive.com. For more information on the integration environment, please see Getting Started.

Data returned with the Metadata API can be used to display specific information on a title or to generate custom collection lists based on specific factors, such as notable reviewers (e.g., The New York Times).

Using the Metadata API

The Metadata API returns detailed information for a specific title. You can navigate to a title's metadata by following the hypermedia links from the Search API results.

Example request:

GET https://api.overdrive.com/v1/collections/v1L1BYwAAAA2Q/products/76c1b7d0-17f4-4c05-8397-c66c17411584/metadata
User-Agent: {Your application}
Authorization: Bearer {OAuth access token}
Host: api.overdrive.com

Example Response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 5593
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Feb 2016 14:28:07 GMT
Expires: -1

{
    "isOwnedByCollections": false,
    "id": "76c1b7d0-17f4-4c05-8397-c66c17411584",
    "CrossRefId": 784864,
    "mediaType": "eBook",
    "title": "The Adventures of Sherlock Holmes",
    "sortTitle": "Adventures of Sherlock Holmes",
    "series": "Sherlock Holmes",
    "publisher": "Duke Classics",
    "creators": [
        { 
            "role": "Author", 
            "name": "Sir Arthur Conan Doyle", 
            "fileAs": "Doyle, Sir Arthur Conan" 
        }
    ],
    "links": {
        "self": { 
            "href": "https://api.overdrive.com/v1/collections/v1L1BYwAAAA2Q/products/76c1b7d0-17f4-4c05-8397-c66c17411584/metadata", 
            "type": "application/vnd.overdrive.api+json" 
        }
    },
    "images": {
        "thumbnail": {
            "href": "https://images.contentreserve.com/ImageType-200/2389-1/
{76C1B7D0-17F4-4C05-8397-C66C17411584}Img200.jpg",
            "type": "image/jpeg"
        },
        "cover150Wide": {
            "href": "https://images.contentreserve.com/ImageType-150/2389-1/76C/1B7/D0/{76C1B7D0-17F4-4C05-8397-C66C17411584
        }
        Img150.jpg",
        "type": "image/jpeg"
    },
    "cover": {
        "href": "https://images.contentreserve.com/ImageType-100/2389-1/
{76C1B7D0-17F4-4C05-8397-C66C17411584}Img100.jpg",
        "type": "image/jpeg"
    },
    "cover300Wide": {
        "href": "https://images.contentreserve.com/ImageType-400/2389-1/76C/1B7/D0/{76C1B7D0-17F4-4C05-8397-C66C17411584}
        Img400.jpg",
        "type": "image/jpeg"
    }
},
    "languages": [
        { 
            "code": "en", 
            "name": "English" 
        }
    ],
    "isPublicDomain": false,
    "isPublicPerformanceAllowed": false,
    "gradeLevels": [
        { 
            "value": "Grade 6" 
        },
        { 
            "value": "Grade 7" 
        },
        { 
            "value": "Grade 8" 
        },
        { 
            "value": "Grade 9" 
        }
    ],
    "shortDescription": "The Adventures of Sherlock Holmes collects Sir Arthur Conan Doyle's first twelve short stories about his famous London detective. It begins with the first meeting of Holmes and his sidekick Watson, who narrates the stories. Doyle was the first to employ the sidekick technique, thereby creating a character in just as much suspense and awe as his readership at the mental escapades of the erratic, terrifyingly intelligent Holmes.",     
    "fullDescription": "The Adventures of Sherlock Holmes collects Sir Arthur Conan Doyle's first twelve short stories about his famous London detective. It begins with the first meeting of Holmes and his sidekick Watson, who narrates the stories. Doyle was the first to employ the sidekick technique, thereby creating a character in just as much suspense and awe as his readership at the mental escapades of the erratic, terrifyingly intelligent Holmes.", 
    "starRating": 4.0, 
    "popularity": 2181, 
    "subjects": [ 
        { 
            "value": "Classic Literature" 
        }, 
        { 
            "value": "Fiction" 
        }, 
        { 
            "value": "Mystery" 
        } 
    ] 
}

You may have noticed that each sample format is listed several times—once for each full format in which a given title is available. For example, the Open EPUB eBook format in the response above lists two sample formats: ebook-epub-adobe and ebook-overdrive.

That means that, although a user may be borrowing an Open EPUB, the samples can be presented in either the Adobe EPUB or OverDrive Read format. We list out every available sample format each time so you can always see what sample formats are available, regardless of what formats are avilable for the full title.

Note: Sometimes the full title format will not match the available sample formats. For example, some MP3 audiobooks only come with WAV samples.

Preorder titles

The only difference between ready-to-circulate titles and preorder titles is the onSaleDate in the Metadata response. In the case of a preorder title, the onSaleDate will show a future date (and thus the title will be unable to circulate even though it's part of the library's collection). Users will still be able to search for and place holds on preorder titles.

Note: Publishers control the onSaleDate, so it may change without warning.

Using the crossRefId

The crossRefId field allows you to create permanent links to titles on overdrive.com and new OverDrive library websites. This means that you can structure a URL to link directly to these two resources from your own application.

https://overdrive.com/media/{crossRefId}

Using the above example, The Adventures of Sherlock Holmes, you can create a simple URL to overdrive.com:

https://overdrive.com/media/784864

Similarly, to create a permanent link to the title on the library's OverDrive website, add the crossRefId to the library's URL:

https://{library}.overdrive.com/media/{crossRefId}

You can also use the crossRefId to create and embed a Readbox, which allows users to interact directly with a title and read a sample without leaving your application. To construct a Readbox, add /sample-embed to an overdrive.com link:

<script type="text/javascript" src="https://www.overdrive.com/media/{crossRefId}/sample-embed"></script>

Making a metadata call on a title that isn't in the collection

It's possible to make a Metadata call for a title that is no longer a part of the collection. When this happens, you'll see a isOwnedByCollections: false line at the very top of the response.

You'll still be able to see the metadata for these titles, but they aren't actually available to borrow through the particular collection (or collections) to which you are making the call.

Making a bulk metadata call

This endpoint works best if you'd like to get metadata for several titles at once. You can ask for the metadata for up to 25 titles at a time by supplying the reserveId for each one. For this to work, all of the titles you're trying to get metadata for will need to be in the collection(s) supplied by the collection token. Everything from the regular Metadata API endpoint applies here too.

Note: The bulk Metadata API will return as many titles as possible, but the totalItems returned may be different than the number you requested.

Example request:

GET https://api.overdrive.com/v1/collections/v1L1BYwAAAA2Q/bulkmetadata?reserveIds=33312cf6-2696-4aae-9b25-59a28874b6e6,679b3696-ef6f-4738-b4b3-363c6b096012
User-Agent: {Your application}
Authorization: Bearer {OAuth access token}
Host: api.overdrive.com

Example Response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 8306
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Feb 2016 14:27:13 GMT
Expires: -1

{
    "metadata": [
        {
            "isOwnedByCollections": true,
            "id": "d9aa61b3-cfbd-4314-9484-5b4f32033d10",
            "mediaType": "eBook",
            "title": "Programming Web  Services with SOAP",
            "sortTitle": "Programming Web  Services with SOAP",
            "series": "Programming",
            "edition": "1",
            "publisher": "O'Reilly Media",
            "publishDate": "2007-08-29T00:00:00-04:00",
            "publishDateText": "08/29/2007",
            "creators": [
                {
                    "role": "Author",
                    "name": "James Snell",
                    "fileAs": "Snell, James"
                },
                {
                    "role": "Author",
                    "name": "Doug Tidwell",
                    "fileAs": "Tidwell, Doug"
                },
                {
                    "role": "Author",
                    "name": "Pavel Kulchenko",
                    "fileAs": "Kulchenko, Pavel"
                }
            ],
            "links": {
                "self": {
                    "href": "https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/products/d9aa61b3-cfbd-4314-9484-5b4f32033d10/metadata",
                    "type": "application/vnd.overdrive.api+json"
                }
            },
            "images": {
                "thumbnail": {
                    "href": "https://images.contentreserve.com/ImageType-200/2858-1/{D9AA61B3-CFBD-4314-9484-5B4F32033D10}Img200.jpg",
                    "type": "image/jpeg"
                },
                "cover150Wide": {
                    "href": "https://images.contentreserve.com/ImageType-150/2858-1/D9A/A61/B3/{D9AA61B3-CFBD-4314-9484-5B4F32033D10}Img150.jpg",
                    "type": "image/jpeg"
                },
                "cover": {
                    "href": "https://images.contentreserve.com/ImageType-100/2858-1/{D9AA61B3-CFBD-4314-9484-5B4F32033D10}Img100.jpg",
                    "type": "image/jpeg"
                },
                "cover300Wide": {
                    "href": "https://images.contentreserve.com/ImageType-400/2858-1/D9A/A61/B3/{D9AA61B3-CFBD-4314-9484-5B4F32033D10}Img400.jpg",
                    "type": "image/jpeg"
                }
            },
            "languages": [
                {
                    "code": "en",
                    "name": "English"
                }
            ],
            "isPublicDomain": false,
            "isPublicPerformanceAllowed": false,
            "shortDescription": "The web services architecture provides a new way to think about and implement application-to-application integration and interoperability that makes the development platform irrelevant. Two applications, regardless of operating system, programming language, or any other technical implementation detail, communicate using XML messages over open Internet protocols such as HTTP or SMTP. The Simple Open Access Protocol (SOAP) is a specification that details how to encode that information and has become the messaging protocol of choice for Web services.Programming Web Services with SOAP  is a detailed guide to using SOAP and other leading web services standards--WSDL (Web Service Description Language), and UDDI (Universal Description, Discovery, and Integration protocol). You'll learn the concepts of the web services architecture and get practical advice on building and deploying web services in the enterprise.This authoritative book decodes the standards, explaining...",
            "fullDescription": "The web services architecture provides a new way to think about and implement application-to-application integration and interoperability that makes the development platform irrelevant. Two applications, regardless of operating system, programming language, or any other technical implementation detail, communicate using XML messages over open Internet protocols such as HTTP or SMTP. The Simple Open Access Protocol (SOAP) is a specification that details how to encode that information and has become the messaging protocol of choice for Web services.Programming Web Services with SOAP  is a detailed guide to using SOAP and other leading web services standards--WSDL (Web Service Description Language), and UDDI (Universal Description, Discovery, and Integration protocol). You'll learn the concepts of the web services architecture and get practical advice on building and deploying web services in the enterprise.This authoritative book decodes the standards, explaining the concepts and implementation in a clear, concise style. You'll also learn about the major toolkits for building and deploying web services. Examples in Java, Perl, C#, and Visual Basic illustrate the principles. Significant applications developed using Java and Perl on the Apache Tomcat web platform address real issues such as security, debugging, and interoperability.Covered topic areas include: The Web Services Architecture SOAP envelopes, headers, and encodings WSDL and UDDI Writing web services with Apache SOAP and Java Writing web services with Perl's SOAP::Lite Peer-to-peer (P2P) web services Enterprise issues such as authentication, security, and identity Up-and-coming standards projects for web services Programming Web Services with SOAP  provides you with all the information on the standards, protocols, and toolkits you'll need to integrate information services with SOAP. You'll find a solid core of information that will help you develop individual Web services or discover new ways to integrate core business processes across an enterprise.",
            "starRating": 0.0,
            "popularity": 1,
            "subjects": [
                {
                    "value": "Computer Technology"
                },
                {
                    "value": "Nonfiction"
                }
            ],
            "keywords": [
                {
                    "value": "XML"
                },
                {
                    "value": "Web services"
                },
                {
                    "value": "Extensible Markup Language"
                },
                {
                    "value": "soap"
                }
            ],
            "formats": [
                {
                    "id": "ebook-pdf-adobe",
                    "name": "Adobe PDF eBook",
                    "fileName": "ProgrammingWebServiceswithSOAP9780596516284",
                    "identifiers": [
                        {
                            "type": "ISBN",
                            "value": "9780596516284"
                        }
                    ],
                    "fileSize": 2258817,
                    "partCount": 0,
                    "onSaleDate": "06/24/2011",
                    "rights": [
                        {
                            "type": "Copying",
                            "value": -1
                        },
                        {
                            "type": "Printing",
                            "value": -1
                        },
                        {
                            "type": "Lending",
                            "value": 0
                        },
                        {
                            "type": "ReadAloud",
                            "value": 1
                        },
                        {
                            "type": "ExpirationRights",
                            "value": 0
                        }
                    ],
                    "samples": [
                        {
                            "source": "From the book",
                            "formatType": "ebook-epub-adobe",
                            "url": "https://excerpts.cdn.overdrive.com/FormatType-410/2858-1/D9A/A61/B3/ProgrammingWebServiceswithSOAP9780596552015.epub"
                        },
                        {
                            "source": "From the book",
                            "formatType": "ebook-overdrive",
                            "url": "https://samples.overdrive.com/?crid=D9AA61B3-CFBD-4314-9484-5B4F32033D10&.epub-sample.overdrive.com"
                        }
                    ]
                },
                {
                    "id": "ebook-epub-adobe",
                    "name": "Adobe EPUB eBook",
                    "fileName": "ProgrammingWebServiceswithSOAP9780596552015",
                    "identifiers": [
                        {
                            "type": "ISBN",
                            "value": "9780596552015"
                        }
                    ],
                    "fileSize": 1129261,
                    "partCount": 0,
                    "onSaleDate": "06/24/2011",
                    "rights": [
                        {
                            "type": "Copying",
                            "value": -1
                        },
                        {
                            "type": "Printing",
                            "value": -1
                        },
                        {
                            "type": "Lending",
                            "value": 0
                        },
                        {
                            "type": "ReadAloud",
                            "value": 1
                        },
                        {
                            "type": "ExpirationRights",
                            "value": 0
                        }
                    ],
                    "samples": [
                        {
                            "source": "From the book",
                            "formatType": "ebook-epub-adobe",
                            "url": "https://excerpts.cdn.overdrive.com/FormatType-410/2858-1/D9A/A61/B3/ProgrammingWebServiceswithSOAP9780596552015.epub"
                        },
                        {
                            "source": "From the book",
                            "formatType": "ebook-overdrive",
                            "url": "https://samples.overdrive.com/?crid=D9AA61B3-CFBD-4314-9484-5B4F32033D10&.epub-sample.overdrive.com"
                        }
                    ]
                },
                {
                    "id": "ebook-kindle",
                    "name": "Kindle Book",
                    "fileName": "ProgrammingWebServiceswithSOAP9780596552015",
                    "identifiers": [
                        {
                            "type": "ASIN",
                            "value": "B0026OR344"
                        }
                    ],
                    "fileSize": 0,
                    "partCount": 0,
                    "onSaleDate": "06/24/2011",
                    "samples": [
                        {
                            "source": "From the book",
                            "formatType": "ebook-epub-adobe",
                            "url": "https://excerpts.cdn.overdrive.com/FormatType-410/2858-1/D9A/A61/B3/ProgrammingWebServiceswithSOAP9780596552015.epub"
                        },
                        {
                            "source": "From the book",
                            "formatType": "ebook-overdrive",
                            "url": "https://samples.overdrive.com/?crid=D9AA61B3-CFBD-4314-9484-5B4F32033D10&.epub-sample.overdrive.com"
                        }
                    ]
                }
            ]
        },
        {
            "isOwnedByCollections": true,
            "id": "c6a44314-382b-4205-9a66-ad83b00248be",
            "mediaType": "Video",
            "title": "Willa's Wild Life, Season 2, Episode 8",
            "subtitle": "Dad's Big News / Little Miss Fitness",
            "sortTitle": "Willas Wild Life Season 02 Episode 08",
            "series": "Willa's Wild Life",
            "publisher": "Nelvana",
            "publishDate": "2014-12-01T00:00:00-05:00",
            "publishDateText": "12/01/2014",
            "creators": [
                {
                    "role": "Copyright holder",
                    "name": "Nelvana",
                    "fileAs": "Nelvana"
                }
            ],
            "links": {
                "self": {
                    "href": "https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/products/c6a44314-382b-4205-9a66-ad83b00248be/metadata",
                    "type": "application/vnd.overdrive.api+json"
                }
            },
            "images": {
                "thumbnail": {
                    "href": "https://images.contentreserve.com/ImageType-200/5802-1/{C6A44314-382B-4205-9A66-AD83B00248BE}Img200.jpg",
                    "type": "image/jpeg"
                },
                "cover150Wide": {
                    "href": "https://images.contentreserve.com/ImageType-150/5802-1/C6A/443/14/{C6A44314-382B-4205-9A66-AD83B00248BE}Img150.jpg",
                    "type": "image/jpeg"
                },
                "cover": {
                    "href": "https://images.contentreserve.com/ImageType-100/5802-1/{C6A44314-382B-4205-9A66-AD83B00248BE}Img100.jpg",
                    "type": "image/jpeg"
                },
                "cover300Wide": {
                    "href": "https://images.contentreserve.com/ImageType-400/5802-1/C6A/443/14/{C6A44314-382B-4205-9A66-AD83B00248BE}Img400.jpg",
                    "type": "image/jpeg"
                }
            },
            "languages": [
                {
                    "code": "en",
                    "name": "English"
                }
            ],
            "isPublicDomain": false,
            "isPublicPerformanceAllowed": false,
            "shortDescription": "Dad finds out that he may have a poem published, but asks Willa not to tell people. However, Willa leaks the news to Dooley, then can't stop the word from spreading. / Inspired by a school health lecture and worried about Dad's tight fitting sweater, Willa becomes Dad's personal trainer. She's determined to get him into shape. But when she enlists her animals to help, Willa discovers that it's best to let Dad get healthy on his own terms – and now she needs to practice what she's been preaching.",
            "fullDescription": "Dad finds out that he may have a poem published, but asks Willa not to tell people. However, Willa leaks the news to Dooley, then can't stop the word from spreading. / Inspired by a school health lecture and worried about Dad's tight fitting sweater, Willa becomes Dad's personal trainer. She's determined to get him into shape. But when she enlists her animals to help, Willa discovers that it's best to let Dad get healthy on his own terms – and now she needs to practice what she's been preaching.",
            "starRating": 0.0,
            "popularity": 0,
            "subjects": [
                {
                    "value": "Cartoon"
                }
            ],
            "keywords": [
                {
                    "value": "Animals"
                },
                {
                    "value": "family"
                },
                {
                    "value": "friends"
                }
            ],
            "formats": [
                {
                    "id": "video-streaming",
                    "name": "Streaming Video",
                    "fileName": "WillasWildLifeSeason02Episode08-922",
                    "fileSize": 0,
                    "partCount": 1,
                    "onSaleDate": "12/05/2014",
                    "rights": [
                        {
                            "type": "DRMType",
                            "value": 0
                        },
                        {
                            "type": "WatchExpiration",
                            "value": 0
                        },
                        {
                            "type": "WatchExpirationHours",
                            "value": -1
                        },
                        {
                            "type": "PublicPerformance",
                            "value": 0
                        },
                        {
                            "type": "ViewOnBrowser",
                            "value": 1
                        },
                        {
                            "type": "ViewOnApp",
                            "value": 1
                        },
                        {
                            "type": "ViewOnSetTop",
                            "value": 1
                        }
                    ],
                    "samples": [
                        {
                            "source": "Part 1",
                            "formatType": "video-streaming",
                            "url": "https://videosamples.overdrive.com/?crid=C6A44314-382B-4205-9A66-AD83B00248BE"
                        }
                    ]
                }
            ]
        }
    ],
    "totalItems": 2,
    "links": {
        "self": {
            "href": "https://api.overdrive.com/v1/collections/v1L1BBQ0AAA2_/BulkMetadata?reserveids=d9aa61b3-cfbd-4314-9484-5b4f32033d10, c6a44314-382b-4205-9a66-ad83b00248be",
            "type": "application/vnd.overdrive.api+json"
        }
    }
}