Click here to skip to this page's main content.

 Hello!   The State of New Jersey is participating in our eBook lending program. Browse the growing lending library of over 250,000 eBooks!

Site Search

Site Search
Last edited by Anand Chitipothu
October 22, 2013 | History

Open Library Books API

The Open Library Books API provides a programmatic client-side method for querying information of books using Javascript.

This API is inspired by the Google Books Dynamic links API and is compatible with it. You can also pass people to an Open Library edition page by using a URL like this: https://openlibrary.org/isbn/123.

API

The API allows requesting information on one or more books using ISBNs, OCLC Numbers, LCCNs and OLIDs (Open Library IDs).

At the core of the API is a URL format that allows developers to construct URLs requesting information on one or more books and send the requests to the Open Library using the <script> tag.

<script src="https://openlibrary.org/api/books?bibkeys=ISBN:0451526538&callback=mycallback"></script>

Request Format

The API supports the following query parameters.

bibkeys

List of IDs to request the information. The API supports ISBNs, LCCNs, OCLC numbers and OLIDs (Open Library IDs).

ISBN

Ex. &bibkeys=ISBN:0451526538 (The API supports both ISBN 10 and 13.)

OCLC

&bibkeys=OCLC:#########

LCCN

&bibkeys=LCCN:#########

OLID

&bibkeys=OLID:OL123M

format

Optional parameter which specifies the response format. Possible values are json and javascript. The default format is javascript.

callback

Optional parameter which specifies the name of the JavaScript function to call with the result. This is considered only when the format is javascript.

jscmd

Optional parameter to decide what information to provide for each matched bib_key. Possible values are viewapi and data. The default value is viewapi.

The Response Format

The response of the API contains a JSON object for each matched bib_key. The contents of the JSON object are decided by the jscmd parameter.

By default, the API returns the response as Javascript.

$ curl 'http://openlibrary.org/api/books?bibkeys=ISBN:0201558025,LCCN:93005405'
var _OLBookInfo = {
    "ISBN:0201558025": {
        ...
    },
    "LCCN:93005405": {
        ...
    }
};

When optional callback parameter is passed, the response is wrapped in a Javascript function call.

$ curl 'https://openlibrary.org/api/books?bibkeys=ISBN:0201558025,LCCN:93005405&callback=processBooks'
processBooks({
    "ISBN:0201558025": {
        ...
    },
    "LCCN:93005405": {
        ...
    }
});

When format=json parameter is passed, the API returns the response as JSON instead of Javascript. This is useful when accessing the API at the server-side.

$ curl 'https://openlibrary.org/api/books?bibkeys=ISBN:0201558025,LCCN:93005405&format=json'
{
    "ISBN:0201558025": {
        ...
    },
    "LCCN:93005405": {
        ...
    }
}

The Data Format

The contents of each JSON object will be decided by the jscmd parameter.

jscmd=viewapi

When jscmd is not specified or when jscmd=viewapi, each JSON object will contain the following:

bib_key

Identifier used to query this book.

info_url

A URL to the book page in the Open Library.

preview

Preview state - either "noview" or "full".

preview_url

A URL to the preview of the book.

This links to the archive.org page when a readable version of the book is available, otherwise it links to the book page on openlibrary.org.

Please note that the preview_url is always provided even if there is no readable version available. The preview property should be used to test if a book is readable.

thumbnail_url

A URL to a thumbnail of the cover of the book. This is provided only when thumbnail is available.

For example:

$ curl 'https://openlibrary.org/api/books?bibkeys=ISBN:0385472579,LCCN:62019420&format=json'
{
    "ISBN:0385472579": {
        "bib_key": "ISBN:0385472579",
        "preview": "noview",
        "thumbnail_url": "https://covers.openlibrary.org/b/id/240726-S.jpg",
        "preview_url": "https://openlibrary.org/books/OL1397864M/Zen_speaks",
        "info_url": "https://openlibrary.org/books/OL1397864M/Zen_speaks"
    },
    "LCCN:62019420": {
        "bib_key": "LCCN:62019420",
        "preview": "full",
        "thumbnail_url": "https://covers.openlibrary.org/b/id/6121771-S.jpg",
        "preview_url": "https://archive.org/details/adventurestomsa00twaigoog",
        "info_url": "https://openlibrary.org/books/OL23377687M/adventures_of_Tom_Sawyer"
    }
}

jscmd=data

When the jscmd=data, data about each matching book is returned. It includes the following:

url

URL of the book

title and subtitle

Title and subtitle of the book.

authors

List of authors. Each entry will be in the following format:

{
    "name": "...",
    "url": "https://openlibrary.org/authors/..."
}

identifiers

All identifiers of the book in the following format:

{
    "isbn_10": [...],
    "isbn_13": [...],
    "lccn": [...],
    "oclc": [...],
    "goodreads": [...]
}

classifications

All classifications of the book in the following format.

{
    "lc_classifications": [...],
    "dewey_decimal_class": [...]
}

subjects, subject_places, subject_people and subject_times

List of subjects, places, people and times of the book. Each entry will be in the following format:

{
    "url": "https://openlibrary.org/subjects/history",
    "name": "History"
}

publishers

List of publishers. Each publisher will be in the following format:

{
    "name": "..."
}

publish_places

List of publish places. Each entry will be in the following format:

{
    "name": "..."
}

publish_date

Published date as a string.

excerpts

List of excerpts to that book. Each entry will be in the following format:

{
    "comment": "...",
    "text": "..."
}

links

List of links to the book. Each link will be in the following format:

{
    "url": "https://...",
    "title": "..."
}

cover

URLs to small, medium and large covers.

{
    "small": "https://covers.openlibrary.org/b/id/1-S.jpg",
    "medium": "https://covers.openlibrary.org/b/id/1-M.jpg",
    "large": "https://covers.openlibrary.org/b/id/1-L.jpg",
}

ebooks

List of ebooks. Each entry will be in the following format:

{
    "preview_url": "https://archive.org/details/..."
}

number_of_pages

Number of pages in that book.

weight

Weight of the book.

For example, here is a sample request.

$ curl 'https://openlibrary.org/api/books?bibkeys=ISBN:9780980200447&jscmd=data&format=json'
{
    "ISBN:9780980200447": {
        "publishers": [
            {
                "name": "Litwin Books"
            }
        ],
        "identifiers": {
            "google": [
                "4LQU1YwhY6kC"
            ],
            "lccn": [
                "2008054742"
            ],
            "isbn_13": [
                "9780980200447"
            ],
            "amazon": [
                "098020044X"
            ],
            "isbn_10": [
                "1234567890"
            ],
            "oclc": [
                "297222669"
            ],
            "librarything": [
                "8071257"
            ],
            "project_gutenberg": [
                "14916"
            ],
            "goodreads": [
                "6383507"
            ]
        },
        "classifications": {
            "dewey_decimal_class": [
                "028/.9"
            ],
            "lc_classifications": [
                "Z1003 .M58 2009"
            ]
        },
        "links": [
            {
                "url": "http://johnmiedema.ca",
                "title": "Author's Website"
            }
        ],
        "weight": "1 grams",
        "title": "Slow reading",
        "url": "https://openlibrary.org/books/OL22853304M/Slow_reading",
        "number_of_pages": 80,
        "cover": {
            "small": "https://covers.openlibrary.org/b/id/5546156-S.jpg",
            "large": "https://covers.openlibrary.org/b/id/5546156-L.jpg",
            "medium": "https://covers.openlibrary.org/b/id/5546156-M.jpg"
        },
        "subjects": [
            {
                "url": "https://openlibrary.org/subjects/books_and_reading",
                "name": "Books and reading"
            },
            {
                "url": "https://openlibrary.org/subjects/reading",
                "name": "Reading"
            }
        ],
        "publish_date": "2009",
        "authors": [
            {
                "url": "https://openlibrary.org/authors/OL6548935A/John_Miedema",
                "name": "John Miedema"
            }
        ],
        "excerpts": [
            {
                "comment": "test purposes",
                "text": "test first page"
            }
        ],
        "publish_places": [
            {
                "name": "Duluth, Minn"
            }
        ]
    }
}

jscmd=details

When jscmd=details is passed, additional details are provided in addition to the info provided by viewapi. The provided details are same as the data provided by the RESTful API.

It is advised to use jscmd=data instead of this as that is more stable format.

$ curl 'https://openlibrary.org/api/books?bibkeys=ISBN:9780980200447&jscmd=details&format=json'
{
    "ISBN:9780980200447": {
        "info_url": "https://openlibrary.org/books/OL22853304M/Slow_reading",
        "bib_key": "ISBN:9780980200447",
        "preview_url": "https://openlibrary.org/books/OL22853304M/Slow_reading",
        "thumbnail_url": "https://covers.openlibrary.org/b/id/5546156-S.jpg",
        "preview": "noview",
        "details": {
            "number_of_pages": 80,
            "table_of_contents": [
                {
                    "title": "The personal nature of slow reading",
                    "type": {
                        "key": "/type/toc_item"
                    },
                    "level": 0
                },
                {
                    "title": "Slow reading in an information ecology",
                    "type": {
                        "key": "/type/toc_item"
                    },
                    "level": 0
                },
                {
                    "title": "The slow movement and slow reading",
                    "type": {
                        "key": "/type/toc_item"
                    },
                    "level": 0
                },
                {
                    "title": "The psychology of slow reading",
                    "type": {
                        "key": "/type/toc_item"
                    },
                    "level": 0
                },
                {
                    "title": "The practice of slow reading.",
                    "type": {
                        "key": "/type/toc_item"
                    },
                    "level": 0
                }
            ],
            "weight": "1 grams",
            "covers": [
                5546156
            ],
            "lc_classifications": [
                "Z1003 .M58 2009"
            ],
            "latest_revision": 14,
            "source_records": [
                "marc:marc_loc_updates/v37.i01.records.utf8:4714764:907",
                "marc:marc_loc_updates/v37.i24.records.utf8:7913973:914",
                "marc:marc_loc_updates/v37.i30.records.utf8:11406606:914"
            ],
            "title": "Slow reading",
            "languages": [
                {
                    "key": "/languages/eng"
                }
            ],
            "subjects": [
                "Books and reading",
                "Reading"
            ],
            "publish_country": "mnu",
            "by_statement": "by John Miedema.",
            "oclc_numbers": [
                "297222669"
            ],
            "type": {
                "key": "/type/edition"
            },
            "physical_dimensions": "1 x 1 x 1 inches",
            "revision": 14,
            "publishers": [
                "Litwin Books"
            ],
            "description": "\"A study of voluntary slow reading from diverse angles\"--Provided by publisher.",
            "physical_format": "Paperback",
            "last_modified": {
                "type": "/type/datetime",
                "value": "2010-08-07T19:35:52.482887"
            },
            "key": "/books/OL22853304M",
            "authors": [
                {
                    "name": "John Miedema",
                    "key": "/authors/OL6548935A"
                }
            ],
            "publish_places": [
                "Duluth, Minn"
            ],
            "pagination": "80p.",
            "classifications": {},
            "created": {
                "type": "/type/datetime",
                "value": "2009-01-07T22:16:11.381678"
            },
            "lccn": [
                "2008054742"
            ],
            "notes": "Includes bibliographical references and index.",
            "identifiers": {
                "amazon": [
                    "098020044X"
                ],
                "google": [
                    "4LQU1YwhY6kC"
                ],
                "project_gutenberg": [
                    "14916"
                ],
                "goodreads": [
                    "6383507"
                ],
                "librarything": [
                    "8071257"
                ]
            },
            "isbn_13": [
                "9780980200447"
            ],
            "dewey_decimal_class": [
                "028/.9"
            ],
            "isbn_10": [
                "1234567890"
            ],
            "publish_date": "2009",
            "works": [
                {
                    "key": "/works/OL13694821W"
                }
            ]
        }
    }
}

Earlier these details were provided when details=true parameter is passed. It is equivalent to jscmd=details and it is retained only for backward-compataibilty.

History Created October 27, 2008 · 17 revisions

October 22, 2013 Edited by Anand Chitipothu changed all urls in example and response to https.
November 10, 2011 Edited by Anand Chitipothu Edited without comment.
September 23, 2011 Edited by mikemccabe typo
August 25, 2011 Edited by Anand Chitipothu clarify preview_url.
October 27, 2008 Created by Anand Chitipothu OL Books API