Skip to content

About

Official Python client for the ISBNLab book metadata API: books by ISBN, authors, publishers, BISAC genres, covers and ISBN conversion.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ISBNLab Python client

The official Python client for the ISBNLab book metadata API. Look up a book by ISBN and get its title, authors, publishers, series, BISAC genres, formats, page count, description and every other edition, from a catalog of more than 100 million editions. It also validates and converts ISBN-10, ISBN-13, EAN and Amazon ASIN.

Install

pip install isbnlab

Python 3.10 or later.

Get an API token

Create a free ISBNLab account and copy your API token from your profile. The Free plan includes 1,000 calls a day; see pricing for more.

Quick start

import os
import isbnlab

config = isbnlab.Configuration(access_token=os.environ["ISBNLAB_API_TOKEN"])

with isbnlab.ApiClient(config) as client:
    books = isbnlab.BooksApi(client)
    book = books.get_book_by_isbn("9780765302304")

    print(book.title)               # The Gathering Storm
    print(book.authors[0].name)     # Robert Jordan
    print(book.publish_date.year if book.publish_date else None)

    print(book.other_editions_count, "other editions")

Many fields are empty for some books, so every field can be None. Field names are snake_case (book.number_of_pages, book.other_editions); book.to_dict() gives the API's own camelCase names.

Linked records carry ids you can look up directly (author, publisher, subject and genre lookups need a Standard or Pro plan):

with isbnlab.ApiClient(config) as client:
    book = isbnlab.BooksApi(client).get_book_by_isbn("9780765302304")
    author = isbnlab.AuthorsApi(client).get_author(str(book.authors[0].id))

    print(author.bio)

Fields that depend on your plan

A book lookup lists the other editions (other_editions, previous_edition, next_edition) on the Pro plan. On the Free and Standard plans those fields are empty, other_editions_count still gives the number of other editions, and two response headers name what was left out: X-Plan-Restricted-Fields lists the fields and X-Plan-Upgrade links to the plans. isbnlab.restricted_fields() and isbnlab.upgrade_url() read them from a ..._with_http_info() call:

with isbnlab.ApiClient(config) as client:
    books = isbnlab.BooksApi(client)
    response = books.get_book_by_isbn_with_http_info("9780765302304")
    book = response.data

    if "otherEditions" in isbnlab.restricted_fields(response):
        print(book.other_editions_count, "other editions; see", isbnlab.upgrade_url(response))
    else:
        for edition in book.other_editions or []:
            print(edition.isbn13, edition.title)

isbnlab.restricted_fields(response) returns every field that was left out by its API name, for example ["otherEditions", "previousEdition", "nextEdition"], or [] when the response is complete.

A cover lookup (Standard or Pro) gives each cover image's URL in covers, and in sizes the same image 200, 400 and 800 pixels wide (w200, w400, w800); a width is None when that size is not available.

cover = books.get_book_cover_by_isbn("9780765302304")
print(cover.sizes[0].w400)  # https://covers.isbnlab.com/w400/9780765302304.jpg

Errors

Any response other than 2xx raises isbnlab.ApiException (or a subclass such as NotFoundException or ForbiddenException). It carries the HTTP status, the headers, and the response body, whose detail explains the reason:

from isbnlab import ApiException

try:
    book = books.get_book_by_isbn("9780000000000")
except ApiException as e:
    if e.status == 404:
        print("Not in the catalog")
    elif e.status == 429:
        print("Daily limit reached; retry after", e.headers.get("Retry-After"), "seconds")
    elif e.status == 403:
        print("Your plan does not include this endpoint")
    else:
        raise

What you can call

Class Method Plan
BooksApi get_book_by_isbn(isbn), get_book_by_asin(asin), get_book_by_id(id) Free
IsbnApi parse_isbn, isbn10_to_isbn13, isbn13_to_isbn10, isbn_to_ean, ean_to_isbn, isbn_to_asin, asin_to_isbn Free
BooksApi get_book_cover_by_isbn(isbn), get_book_cover_by_asin(asin) Standard
AuthorsApi get_author(id), find_author(search) Standard
PublishersApi get_publisher(id), find_publisher(search), get_publishers_by_prefix(prefix) Standard
SubjectsApi get_subject(id), find_subject(search) Standard
GenresApi get_genre(id), find_genre(search) (name or BISAC code) Standard
BooksApi search_books(query, limit=, page=, max_results=) Pro
BooksApi get_editions_by_isbn(isbn), get_editions_by_asin(asin) Pro

Every method also has a ..._with_http_info() version that returns the status code and headers as well (for example the rate-limit headers).

Reference for every method and model: docs/. Field-by-field documentation: API documentation.

Development

isbnlab/ and docs/ are generated from the API's OpenAPI document with OpenAPI Generator, so changes to them are made in the generator and arrive with the next release; please open an issue rather than a pull request for those folders. README.md, pyproject.toml and tests/ are maintained by hand.

pip install -e ".[test]"
pytest

License

MIT. Maintained by ISBNLab, the book metadata API.

About

Official Python client for the ISBNLab book metadata API: books by ISBN, authors, publishers, BISAC genres, covers and ISBN conversion.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages