This document is intended for developers who want to write applications that can interact with the Google Books API. Google Books has a vision to digitize the world's books. You can use the Google Books API to search content, organize an authenticated user's personal library and modify it as well.
openapi: 3.1.0
info:
title: Google Books API
description: API for retrieving Bookshelf and Volume resources from Google Books
version: 1.0.0
contact:
name: Google Books API
url: https://developers.google.com/books
servers:
- url: https://www.googleapis.com/books/v1
description: Google Books API v1
paths:
/volumes:
get:
summary: Google List Volumes
description: Performs a book search. Returns a list of volumes that match the search query.
operationId: listVolumes
tags:
- Volumes
parameters:
- name: q
in: query
required: true
description: Full-text search query string
schema:
type: string
example: "flowers"
- name: download
in: query
required: false
description: Restrict to volumes by download availability
schema:
type: string
enum:
- epub
example: "epub"
- name: filter
in: query
required: false
description: Filter search results
schema:
type: string
enum:
- ebooks
- free-ebooks
- full
- paid-ebooks
- partial
example: "ebooks"
- name: langRestrict
in: query
required: false
description: Restrict results to books with this language code
schema:
type: string
example: "en"
- name: libraryRestrict
in: query
required: false
description: Restrict search to this user's library
schema:
type: string
enum:
- my-library
- no-restrict
example: "no-restrict"
- name: maxResults
in: query
required: false
description: Maximum number of results to return (0 to 40)
schema:
type: integer
minimum: 0
maximum: 40
default: 10
example: 10
- name: orderBy
in: query
required: false
description: Sort search results
schema:
type: string
enum:
- newest
- relevance
example: "relevance"
- name: partner
in: query
required: false
description: Restrict and brand results for partner ID
schema:
type: string
- name: printType
in: query
required: false
description: Restrict to books or magazines
schema:
type: string
enum:
- all
- books
- magazines
example: "all"
- name: projection
in: query
required: false
description: Restrict information returned to a set of selected fields
schema:
type: string
enum:
- full
- lite
example: "full"
- name: showPreorders
in: query
required: false
description: Set to true to show books available for preorder
schema:
type: boolean
default: false
example: false
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
- name: startIndex
in: query
required: false
description: Index of the first result to return (starts at 0)
schema:
type: integer
minimum: 0
default: 0
example: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/VolumesResponse'
example:
kind: "books#volumes"
totalItems: 1234
items:
- kind: "books#volume"
id: "zyTCAlFPjgYC"
etag: "oTRt82b5z/Q"
selfLink: "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC"
volumeInfo:
title: "The Google Story"
authors: ["David A. Vise", "Mark Malseed"]
publisher: "Delacorte Press"
publishedDate: "2005-11-15"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/volumes/{volumeId}:
get:
summary: Google Get Volume
description: Retrieves a Volume resource based on ID. More information about volume IDs can be found in the Google Books IDs section.
operationId: getVolume
tags:
- Volumes
parameters:
- name: volumeId
in: path
required: true
description: ID of volume to retrieve
schema:
type: string
example: "zyTCAlFPjgYC"
- name: partner
in: query
required: false
description: Brand results for partner ID
schema:
type: string
- name: projection
in: query
required: false
description: Restrict information returned to a set of selected fields
schema:
type: string
enum:
- full
- lite
example: "full"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
example:
kind: "books#volume"
id: "zyTCAlFPjgYC"
etag: "oTRt82b5z/Q"
selfLink: "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC"
volumeInfo:
title: "The Google Story"
authors: ["David A. Vise", "Mark Malseed"]
publisher: "Delacorte Press"
publishedDate: "2005-11-15"
pageCount: 207
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Volume not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/users/{userId}/bookshelves:
get:
summary: Google List Bookshelves
description: Retrieves a list of public Bookshelf resources for the specified user. More information about user IDs can be found in the Google Books IDs section.
operationId: listBookshelves
tags:
- Bookshelves
parameters:
- name: userId
in: path
required: true
description: ID of user for whom to retrieve bookshelves
schema:
type: string
example: "112624903452243252365"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BookshelvesResponse'
example:
kind: "books#bookshelves"
items:
- kind: "books#bookshelf"
id: 0
title: "Favorites"
volumeCount: 42
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/users/{userId}/bookshelves/{shelf}:
get:
summary: Google Get Bookshelf
description: Retrieves a specific Bookshelf resource for the specified user. More information about user IDs can be found in the Google Books IDs section.
operationId: getBookshelf
tags:
- Bookshelves
parameters:
- name: userId
in: path
required: true
description: ID of user for whom to retrieve bookshelves
schema:
type: string
example: "112624903452243252365"
- name: shelf
in: path
required: true
description: ID of bookshelf to retrieve
schema:
type: string
example: "0"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Bookshelf'
example:
kind: "books#bookshelf"
id: 0
title: "Favorites"
access: "PUBLIC"
volumeCount: 42
selfLink: "https://www.googleapis.com/books/v1/users/112624903452243252365/bookshelves/0"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/users/{userId}/bookshelves/{shelf}/volumes:
get:
summary: Google List Bookshelf Volumes
description: Retrieves volumes in a specific bookshelf for the specified user.
operationId: listBookshelfVolumes
tags:
- Bookshelves
parameters:
- name: userId
in: path
required: true
description: ID of user for whom to retrieve bookshelf volumes
schema:
type: string
example: "112624903452243252365"
- name: shelf
in: path
required: true
description: ID of bookshelf to retrieve volumes
schema:
type: string
example: "0"
- name: maxResults
in: query
required: false
description: Maximum number of results to return
schema:
type: integer
minimum: 0
example: 10
- name: showPreorders
in: query
required: false
description: Set to true to show pre-ordered books
schema:
type: boolean
default: false
example: false
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
- name: startIndex
in: query
required: false
description: Index of the first element to return (starts at 0)
schema:
type: integer
minimum: 0
default: 0
example: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/VolumesResponse'
example:
kind: "books#volumes"
totalItems: 42
items:
- kind: "books#volume"
id: "zyTCAlFPjgYC"
volumeInfo:
title: "The Google Story"
authors: ["David A. Vise", "Mark Malseed"]
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves:
get:
summary: Google List My Bookshelves
description: Retrieves a list of bookshelves belonging to the authenticated user.
operationId: listMyBookshelves
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BookshelvesResponse'
example:
kind: "books#bookshelves"
items:
- kind: "books#bookshelf"
id: 0
title: "Favorites"
access: "PRIVATE"
volumeCount: 42
- kind: "books#bookshelf"
id: 1
title: "Reading now"
access: "PRIVATE"
volumeCount: 3
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves/{shelf}:
get:
summary: Google Get My Bookshelf
description: Retrieves metadata for a specific bookshelf belonging to the authenticated user.
operationId: getMyBookshelf
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: shelf
in: path
required: true
description: ID of bookshelf to retrieve
schema:
type: string
example: "0"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Bookshelf'
example:
kind: "books#bookshelf"
id: 0
title: "Favorites"
access: "PRIVATE"
volumeCount: 42
selfLink: "https://www.googleapis.com/books/v1/mylibrary/bookshelves/0"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves/{shelf}/addVolume:
post:
summary: Google Add Volume to Bookshelf
description: Adds a volume to a bookshelf in the authenticated user's library. Requires authorization.
operationId: addVolumeToBookshelf
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: shelf
in: path
required: true
description: ID of bookshelf to which to add a volume
schema:
type: string
example: "0"
- name: volumeId
in: query
required: true
description: ID of volume to add
schema:
type: string
example: "zyTCAlFPjgYC"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'204':
description: Volume successfully added to bookshelf (empty response body)
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf or volume not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves/{shelf}/clearVolumes:
post:
summary: Google Clear Volumes from Bookshelf
description: Clears all volumes from a bookshelf in the authenticated user's library. Requires authorization.
operationId: clearVolumesFromBookshelf
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: shelf
in: path
required: true
description: ID of bookshelf from which to remove all volumes
schema:
type: string
example: "0"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'204':
description: All volumes successfully cleared from bookshelf (empty response body)
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves/{shelf}/moveVolume:
post:
summary: Google Move Volume in Bookshelf
description: Moves a volume within a bookshelf in the authenticated user's library. Requires authorization.
operationId: moveVolumeInBookshelf
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: shelf
in: path
required: true
description: ID of bookshelf with the volume
schema:
type: string
example: "0"
- name: volumeId
in: query
required: true
description: ID of volume to move
schema:
type: string
example: "zyTCAlFPjgYC"
- name: volumePosition
in: query
required: true
description: Position on shelf to move the item (0 puts the item before the current first item, 1 puts it between the first and the second and so on)
schema:
type: integer
minimum: 0
example: 0
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'204':
description: Volume successfully moved in bookshelf (empty response body)
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf or volume not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves/{shelf}/removeVolume:
post:
summary: Google Remove Volume from Bookshelf
description: Removes a volume from a bookshelf in the authenticated user's library. Requires authorization.
operationId: removeVolumeFromBookshelf
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: shelf
in: path
required: true
description: ID of bookshelf from which to remove a volume
schema:
type: string
example: "0"
- name: volumeId
in: query
required: true
description: ID of volume to remove
schema:
type: string
example: "zyTCAlFPjgYC"
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
responses:
'204':
description: Volume successfully removed from bookshelf (empty response body)
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf or volume not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/mylibrary/bookshelves/{shelf}/volumes:
get:
summary: Google List My Bookshelf Volumes
description: Gets volume information for volumes on a bookshelf belonging to the authenticated user.
operationId: listMyBookshelfVolumes
tags:
- My Library
security:
- OAuth2:
- https://www.googleapis.com/auth/books
parameters:
- name: shelf
in: path
required: true
description: The bookshelf ID or name to retrieve volumes for
schema:
type: string
example: "0"
- name: maxResults
in: query
required: false
description: Maximum number of results to return
schema:
type: integer
minimum: 0
example: 10
- name: projection
in: query
required: false
description: Restrict information returned to a set of selected fields
schema:
type: string
enum:
- full
- lite
example: "full"
- name: q
in: query
required: false
description: Full-text search query string in this bookshelf
schema:
type: string
example: "flowers"
- name: showPreorders
in: query
required: false
description: Set to true to show pre-ordered books
schema:
type: boolean
default: false
example: false
- name: source
in: query
required: false
description: String to identify the originator of this request
schema:
type: string
- name: startIndex
in: query
required: false
description: Index of the first element to return (starts at 0)
schema:
type: integer
minimum: 0
default: 0
example: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/VolumesResponse'
example:
kind: "books#volumes"
totalItems: 42
items:
- kind: "books#volume"
id: "zyTCAlFPjgYC"
volumeInfo:
title: "The Google Story"
authors: ["David A. Vise", "Mark Malseed"]
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - requires authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Bookshelf not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
VolumesResponse:
type: object
description: Response containing a list of volumes from a search
required:
- kind
properties:
kind:
type: string
description: Resource type
enum:
- books#volumes
example: "books#volumes"
totalItems:
type: integer
description: Total number of volumes found. This might be greater than the number of volumes returned in this response if results have been paginated.
example: 1234
items:
type: array
description: A list of volumes
items:
$ref: '#/components/schemas/Volume'
Volume:
type: object
description: A Volume represents information that Google Books hosts about a book or a magazine. It contains metadata, such as title and author, as well as personalized data, such as whether or not it has been purchased.
properties:
kind:
type: string
description: Resource type for a volume. (In LITE projection.)
enum:
- books#volume
example: "books#volume"
id:
type: string
description: Unique identifier for a volume. (In LITE projection.)
example: "zyTCAlFPjgYC"
etag:
type: string
description: Opaque identifier for a specific version of a volume resource. (In LITE projection)
example: "oTRt82b5z/Q"
selfLink:
type: string
format: uri
description: URL to this resource. (In LITE projection.)
example: "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC"
volumeInfo:
type: object
description: General volume information.
properties:
title:
type: string
description: Volume title. (In LITE projection.)
example: "The Google Story"
subtitle:
type: string
description: Volume subtitle. (In LITE projection.)
authors:
type: array
description: The names of the authors and/or editors for this volume. (In LITE projection)
items:
type: string
example: ["David A. Vise", "Mark Malseed"]
publisher:
type: string
description: Publisher of this volume. (In LITE projection.)
example: "Delacorte Press"
publishedDate:
type: string
description: Date of publication. (In LITE projection.)
example: "2005-11-15"
description:
type: string
description: A synopsis of the volume. The text of the description is formatted in HTML and includes simple formatting elements, such as b, i, and br tags. (in LITE projection)
industryIdentifiers:
type: array
description: Industry standard identifiers for this volume.
items:
type: object
properties:
type:
type: string
description: Identifier type. Possible values are ISBN_10, ISBN_13, ISSN and OTHER.
enum:
- ISBN_10
- ISBN_13
- ISSN
- OTHER
example: "ISBN_10"
identifier:
type: string
description: Industry specific volume identifier.
example: "0553804677"
pageCount:
type: integer
description: Total number of pages.
example: 207
dimensions:
type: object
description: Physical dimensions of this volume.
properties:
height:
type: string
description: Height or length of this volume (in cm).
example: "24.00 cm"
width:
type: string
description: Width of this volume (in cm).
example: "16.00 cm"
thickness:
type: string
description: Thickness of this volume (in cm).
example: "2.00 cm"
printType:
type: string
description: Type of publication of this volume. Possible values are BOOK or MAGAZINE.
enum:
- BOOK
- MAGAZINE
example: "BOOK"
mainCategory:
type: string
description: The main category to which this volume belongs. It will be the category from the categories list returned below that has the highest weight.
example: "Business & Economics"
categories:
type: array
description: A list of subject categories, such as "Fiction", "Suspense", etc.
items:
type: string
example: ["Business & Economics", "Corporate & Business History"]
averageRating:
type: number
format: double
description: The mean review rating for this volume. (min = 1.0, max = 5.0)
minimum: 1.0
maximum: 5.0
example: 4.0
ratingsCount:
type: integer
description: The number of review ratings for this volume.
example: 123
contentVersion:
type: string
description: An identifier for the version of the volume content (text & images). (In LITE projection)
example: "1.2.3.4.preview.3"
imageLinks:
type: object
description: A list of image links for all the sizes that are available. (in LITE projection)
properties:
smallThumbnail:
type: string
format: uri
description: Image link for small thum
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google/refs/heads/main/openapi/books-api-openapi.yml