openapi: 3.2.0
info:
title: ISBNdb API v2 Books API
description: "Definition of ISBNdb.com API v2.\n\n***Note: A 404 Not Found response for an ISBN lookup typically\nindicates that the book information is not yet available in our database.\nHowever, due to frequent updates, there is a high probability that the data will be \nadded shortly, often within a minute or up to 24 hours. We recommend trying your request \nagain after a while, as the information may soon become accessible***\n"
version: 2.7.0
servers:
- url: https://api2.isbndb.com
description: API Endpoint
tags:
- name: Books
description: Books
paths:
/book/{isbn}:
get:
tags:
- Books
summary: Get book details by isbn.
description: "Returns the book details. \n \n**A 404 Not Found response for an ISBN lookup typically indicates that the book information is not yet available\nin our database. However, due to frequent updates, there is a high probability that the data will be added shortly,\noften within a minute or up to 24 hours. We recommend trying your request again after a while, as the information\nmay soon become accessible.**"
operationId: get_app_api_book_book__invoke
parameters:
- name: with_prices
in: query
description: "Whether to include prices in the response. \n\n***Available starting from Pro plan***\n\n***Performance Impact:*** Enabling this will increase response time, as current prices are fetched from vendors in real-time."
required: false
schema:
type: boolean
default: false
- name: isbn
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns the book details
content:
application/json:
schema:
$ref: '#/components/schemas/GetBookResponse'
'404':
description: Book not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- ApiKeyAuth: []
/books:
post:
tags:
- Books
summary: Search books
description: "\nRetrieves a list of books matching the provided array of ISBNs. This endpoint is available on all plans and does not use pagination.\n\n**Request Limits per Plan:**\n* **Academic:** Up to 10 ISBNs per request.\n* **Basic:** Up to 100 ISBNs per request.\n* **Pro, Premium, and higher:** Up to 1,000 ISBNs per request.\n\n**Quota Usage (Important):** Each requested ISBN counts as a separate API call against your daily limit. For example, a single request containing 100 ISBNs will deduct 100 calls from your daily quota.\n\n**Response Behavior:**\n* The response will only include books that successfully match an ISBN in our database. \n* Any submitted ISBNs that are not found will be silently ignored and excluded from the response.\n* **Note:** Pricing information is not returned by this endpoint.\n"
operationId: post_app_api_book_bookmultiple__invoke
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetBooksMultipleRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/GetBooksMultipleRequest'
responses:
'200':
description: Returns books details
content:
application/json:
schema:
$ref: '#/components/schemas/GetBooksMultipleResponse'
security:
- ApiKeyAuth: []
/books/{query}:
get:
tags:
- Books
summary: Search books
description: 'This returns a list of books that match the query.
**This endpoint does not return pricing information.**'
operationId: get_app_api_book_searchbook__invoke
parameters:
- name: query
in: path
description: 'The search query string. **Max length: 150 characters**.'
required: true
schema:
type: string
pattern: .+
- name: year
in: query
description: Filter books by year of publication
required: false
schema:
description: Filter books by year of publication
type:
- integer
- 'null'
default: null
- name: edition
in: query
description: Filter books by edition
required: false
schema:
description: Filter books by edition
type:
- integer
- 'null'
default: null
- name: shouldMatchAll
in: query
description: "If set to `1` or `true`, the API will return books where the title \n or author exactly contains all the words entered by the user."
required: false
schema:
description: "If set to `1` or `true`, the API will return books where the title \n or author exactly contains all the words entered by the user."
type:
- boolean
- 'null'
default: false
- name: column
in: query
description: 'Search limited to this column:
* `` - Empty value search in every column
* `title` - Only searches in Books Title
* `author` - Only searches books by the given Author
* `date_published` - Only searches books in a given year, e.g. 1998
* `subjects` - Only searches books by the given subject, e.g. physics'
required: false
schema:
description: 'Search limited to this column:
* `` - Empty value search in every column
* `title` - Only searches in Books Title
* `author` - Only searches books by the given Author
* `date_published` - Only searches books in a given year, e.g. 1998
* `subjects` - Only searches books by the given subject, e.g. physics'
type:
- string
- 'null'
default: null
enum:
- title
- author
- date_published
- subjects
- name: language
in: query
description: Language code to filter books by language (e.g., `eng` for English, `fra` for French, etc.)
required: false
schema:
description: Language code to filter books by language (e.g., `eng` for English, `fra` for French, etc.)
type:
- string
- 'null'
default: null
maxLength: 50
- name: page
in: query
description: The number of page to retrieve, please note the API will not return more than 10,000 results no matter how you paginate them
required: false
schema:
description: The number of page to retrieve, please note the API will not return more than 10,000 results no matter how you paginate them
type:
- integer
- 'null'
default: 1
- name: pageSize
in: query
description: How many items should be returned per page, maximum of 1,000
required: false
schema:
description: How many items should be returned per page, maximum of 1,000
type:
- integer
- 'null'
default: 20
- name: publishedFrom
in: query
description: 'Filter books published on or after this date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`. Cannot be combined with the `year` parameter.'
required: false
schema:
description: 'Filter books published on or after this date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`. Cannot be combined with the `year` parameter.'
type:
- string
- 'null'
pattern: .*(^\d{4}(-(0[1-9]|1[0-2])(-(0[1-9]|[12]\d|3[01]))?)?$).*
default: null
- name: publishedTo
in: query
description: 'Filter books published on or before this date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`. Cannot be combined with the `year` parameter.'
required: false
schema:
description: 'Filter books published on or before this date. Accepted formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`. Cannot be combined with the `year` parameter.'
type:
- string
- 'null'
pattern: .*(^\d{4}(-(0[1-9]|1[0-2])(-(0[1-9]|[12]\d|3[01]))?)?$).*
default: null
responses:
'200':
description: Returns the book details
content:
application/json:
schema:
$ref: '#/components/schemas/GetBooksMultipleResponse'
security:
- ApiKeyAuth: []
components:
schemas:
GetBookResponse:
required:
- book
properties:
book:
$ref: '#/components/schemas/Book'
type: object
GetBooksMultipleResponse:
required:
- total
- data
properties:
total:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/Book'
requested:
type:
- integer
- 'null'
default: null
type: object
Point:
required:
- x
- y
properties:
x:
type: string
y:
type: string
type: object
GetBooksMultipleRequest:
required:
- isbns
properties:
isbns:
oneOf:
- type: array
items:
oneOf:
- type: integer
- type: string
- type: object
additionalProperties:
oneOf:
- type: integer
- type: string
type: object
Book:
required:
- title
- title_long
- isbn
- isbn13
- date_published
properties:
title:
description: Title
type: string
title_long:
description: Title
type: string
deprecated: true
isbn:
description: ISBN-13
type: string
deprecated: true
isbn13:
description: ISBN-13
type: string
isbn10:
description: Book ISBN-10, if available
type:
- string
- 'null'
binding:
description: Book binding type (e.g. Hardcover, Paperback, eBook)
type:
- string
- 'null'
publisher:
description: Name of the publisher
type:
- string
- 'null'
language:
description: Language of the book (ISO 639-1 code or full name)
type:
- string
- 'null'
date_published:
description: A publication date in YYYY-MM-DD, YYYY-MM, or YYYY format.
type: string
format: date
example: '2023-10-26'
edition:
description: Edition of the book (e.g. 3rd, Revised)
type:
- string
- 'null'
pages:
description: Number of pages in the book
type:
- integer
- 'null'
dimensions:
description: Physical dimensions of the book as a formatted string
type:
- string
- 'null'
deprecated: true
dimensions_structured:
description: Structured physical dimensions of the book (height, width, weight, etc.)
oneOf:
- type: array
items: {}
- type: object
additionalProperties: {}
overview:
description: Brief overview or description of the book
type:
- string
- 'null'
deprecated: true
image:
description: Image link. Maximum height is 500px.
type:
- string
- 'null'
image_original:
description: 'Original image link. Note: This URL is temporary and will expire 2 hours after the API response is generated.'
type:
- string
- 'null'
msrp:
description: Manufacturer's suggested retail price
type:
- number
- 'null'
format: float
excerpt:
description: Short excerpt from the book
type:
- string
- 'null'
synopsis:
description: Full synopsis or summary of the book
type:
- string
- 'null'
authors:
description: List of authors of the book
type:
- array
- 'null'
items:
type: string
subjects:
description: List of subjects or categories the book belongs to
type:
- array
- 'null'
items:
type: string
reviews:
description: User or editorial reviews of the book
type:
- array
- 'null'
items:
type: string
deprecated: true
prices:
description: Available prices from various merchants
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Price'
related:
description: Related books
deprecated: true
oneOf:
- type: array
items: {}
- type: object
additionalProperties: {}
other_isbns:
description: Other ISBNs associated with this book (e.g. different formats or editions)
type:
- array
- 'null'
items:
$ref: '#/components/schemas/RelatedIsbn'
type: object
ErrorResponse:
required:
- message
- error_message
properties:
message:
type: string
deprecated: true
error_message:
type: string
type: object
RelatedIsbn:
required:
- isbn
- binding
properties:
isbn:
description: ISBN-13 of the related edition
type: string
binding:
description: Binding type of the related edition (e.g. Hardcover, Paperback)
type: string
type: object
Price:
required:
- condition
- merchant
- merchant_logo
- merchant_logo_offset
- shipping
- price
- total
- link
properties:
condition:
description: Condition of the book offered at this price (e.g. new, used, digital)
type: string
merchant:
description: Name of the merchant offering this price
type: string
merchant_logo:
description: URL of the merchant logo image
type: string
merchant_logo_offset:
$ref: '#/components/schemas/Point'
shipping:
description: Shipping cost for this offer
type: string
price:
description: Item price excluding shipping
type: string
total:
description: Total price including shipping
type: string
link:
description: URL to purchase the book from this merchant
type: string
type: object
securitySchemes:
ApiKeyAuth:
type: apiKey
name: Authorization
in: header