openapi: 3.1.0 info: title: Google Books About Volumes 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 tags: - name: Volumes 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' components: schemas: Error: type: object description: Error response properties: error: type: object properties: code: type: integer description: HTTP status code example: 404 message: type: string description: Error message example: User not found errors: type: array items: type: object properties: domain: type: string example: global reason: type: string example: notFound message: type: string example: User not found 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 thumbnail size (width of ~80 pixels). (in LITE projection) thumbnail: type: string format: uri description: Image link for thumbnail size (width of ~128 pixels). (in LITE projection) small: type: string format: uri description: Image link for small size (width of ~300 pixels). (in LITE projection) medium: type: string format: uri description: Image link for medium size (width of ~575 pixels). (in LITE projection) large: type: string format: uri description: Image link for large size (width of ~800 pixels). (in LITE projection) extraLarge: type: string format: uri description: Image link for extra large size (width of ~1280 pixels). (in LITE projection) language: type: string description: Best language for this volume (based on content). It is the two-letter ISO 639-1 code such as 'fr', 'en', etc. example: en previewLink: type: string format: uri description: URL to preview this volume on the Google Books site. infoLink: type: string format: uri description: URL to view information about this volume on the Google Books site. (In LITE projection) canonicalVolumeLink: type: string format: uri description: Canonical URL for a volume. (In LITE projection.) userInfo: type: object description: User specific information related to this volume. (e.g. page this user last read or whether they purchased this book) properties: review: type: object description: This user's review of this volume, if one exists. readingPosition: type: object description: The user's current reading position in the volume, if one is available. (In LITE projection.) isPurchased: type: boolean description: Whether or not this volume was purchased by the authenticated user making the request. (In LITE projection.) isPreordered: type: boolean description: Whether or not this volume was pre-ordered by the authenticated user making the request. (In LITE projection.) updated: type: string format: date-time description: Timestamp when this volume was last modified by a user action, such as a reading position update, volume purchase or writing a review. (RFC 3339 UTC date-time format). saleInfo: type: object description: Any information about a volume related to the eBookstore and/or purchaseability. This information can depend on the country where the request originates from (i.e. books may not be for sale in certain countries). properties: country: type: string description: The two-letter ISO_3166-1 country code for which this sale information is valid. (In LITE projection.) example: US saleability: type: string description: Whether or not this book is available for sale or offered for free in the Google eBookstore for the country listed above. Possible values are FOR_SALE, FREE, NOT_FOR_SALE, or FOR_PREORDER. enum: - FOR_SALE - FREE - NOT_FOR_SALE - FOR_PREORDER example: FOR_SALE onSaleDate: type: string format: date-time description: The date on which this book is available for sale. isEbook: type: boolean description: Whether or not this volume is an eBook (can be added to the My eBooks shelf). example: true listPrice: type: object description: Suggested retail price. (in LITE projection) properties: amount: type: number format: double description: Amount in the currency listed below. (In LITE projection.) example: 9.99 currencyCode: type: string description: An ISO 4217, three-letter currency code. (In LITE projection.) example: USD retailPrice: type: object description: The actual selling price of the book. This is the same as the suggested retail or list price unless there are offers or discounts on this volume. (in LITE projection) properties: amount: type: number format: double description: Amount in the currency listed below. (In LITE projection.) example: 9.99 currencyCode: type: string description: An ISO 4217, three-letter currency code. (In LITE projection.) example: USD buyLink: type: string format: uri description: URL to purchase this volume on the Google Books site. (in LITE projection) accessInfo: type: object description: Any information about a volume related to reading or obtaining that volume text. This information can depend on country (books may be public domain in one country but not in another, e.g.). properties: country: type: string description: The two-letter ISO_3166-1 country code for which this access information is valid. (In LITE projection.) example: US viewability: type: string description: The read access of a volume. Possible values are PARTIAL, ALL_PAGES, NO_PAGES or UNKNOWN. This value depends on the country listed above. A value of PARTIAL means that the publisher has allowed some portion of the volume to be viewed publicly, without purchase. This can apply to eBooks as well as non-eBooks. Public domain books will always have a value of ALL_PAGES. enum: - PARTIAL - ALL_PAGES - NO_PAGES - UNKNOWN example: PARTIAL embeddable: type: boolean description: Whether this volume can be embedded in a viewport using the Embedded Viewer API. example: true publicDomain: type: boolean description: Whether or not this book is public domain in the country listed above. example: false textToSpeechPermission: type: string description: Whether text-to-speech is permitted for this volume. Values can be ALLOWED, ALLOWED_FOR_ACCESSIBILITY, or NOT_ALLOWED. enum: - ALLOWED - ALLOWED_FOR_ACCESSIBILITY - NOT_ALLOWED example: ALLOWED epub: type: object description: Information about epub content. (in LITE projection) properties: isAvailable: type: boolean description: Is a flowing text epub available either as public domain or for purchase. (In LITE projection.) example: true downloadLink: type: string format: uri description: URL to download epub. (In LITE projection.) acsTokenLink: type: string format: uri description: URL to retrieve ACS token for epub download. (In LITE projection.) pdf: type: object description: Information about pdf content. (in LITE projection) properties: isAvailable: type: boolean description: Is a scanned image pdf available either as public domain or for purchase. (In LITE projection.) example: false downloadLink: type: string format: uri description: URL to download pdf. (In LITE projection.) acsTokenLink: type: string format: uri description: URL to retrieve ACS token for pdf download. (In LITE projection.) webReaderLink: type: string format: uri description: URL to read this volume on the Google Books site. Link will not allow users to read non-viewable volumes. accessViewStatus: type: string description: Combines the access and viewability of this volume into a single status field for this user. Values can be FULL_PURCHASED, FULL_PUBLIC_DOMAIN, SAMPLE or NONE. (In LITE projection.) enum: - FULL_PURCHASED - FULL_PUBLIC_DOMAIN - SAMPLE - NONE example: SAMPLE downloadAccess: type: object description: Information about a volume's download license access restrictions. properties: kind: type: string description: Resource type. enum: - books#downloadAccessRestriction volumeId: type: string description: Identifies the volume for which this entry applies. restricted: type: boolean description: Whether this volume has any download access restrictions. deviceAllowed: type: boolean description: If restricted, whether access is granted for this (user, device, volume). justAcquired: type: boolean description: If deviceAllowed, whether access was just acquired with this request. maxDownloadDevices: type: integer description: If restricted, the maximum number of content download licenses for this volume. downloadsAcquired: type: integer description: If restricted, the number of content download licenses already acquired (including the requesting client, if licensed). nonce: type: string description: Client nonce for verification. Download access and client-validation only. source: type: string description: Client app identifier for verification. Download access and client-validation only. reasonCode: type: string description: Error/warning reason code. Additional codes may be added in the future. 0 OK, 100 ACCESS_DENIED_PUBLISHER_LIMIT, 101 ACCESS_DENIED_LIMIT, 200 WARNING_USED_LAST_ACCESS message: type: string description: Error/warning message. signature: type: string description: Response signature. searchInfo: type: object description: Search result information related to this volume. properties: textSnippet: type: string description: A text snippet containing the search query. securitySchemes: OAuth2: type: oauth2 description: OAuth 2.0 authentication for Google Books API flows: authorizationCode: authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth tokenUrl: https://oauth2.googleapis.com/token scopes: https://www.googleapis.com/auth/books: Manage your Google Books library