Google Volumes API

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