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 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.

    BookshelvesResponse:
      type: object
      description: Response containing a list of bookshelves
      required:
        - kind
      properties:
        kind:
          type: string
          description: Resource type
          enum:
            - books#bookshelves
          example: "books#bookshelves"
        items:
          type: array
          description: A list of bookshelves
          items:
            $ref: '#/components/schemas/Bookshelf'
    Bookshelf:
      type: object
      description: A bookshelf resource represents the metadata for a bookshelf, it does not include the volumes in the bookshelf
      properties:
        kind:
          type: string
          description: Resource type for bookshelf metadata
          enum:
            - books#bookshelf
          example: "books#bookshelf"
        id:
          type: integer
          description: ID of this bookshelf
          example: 0
        selfLink:
          type: string
          format: uri
          description: URL to this resource
          example: "https://www.googleapis.com/books/v1/users/112624903452243252365/bookshelves/0"
        title:
          type: string
          description: Title of this bookshelf
          example: "Favorites"
        description:
          type: string
          description: Description of this bookshelf
          example: "My favorite books to read"
        access:
          type: string
          description: Whether this bookshelf is PUBLIC or PRIVATE
          enum:
            - PUBLIC
            - PRIVATE
          example: "PUBLIC"
        updated:
          type: string
          format: date-time
          description: Last modified time of this bookshelf (formatted UTC timestamp with millisecond resolution)
          example: "2024-01-15T10:30:00.000Z"
        created:
          type: string
          format: date-time
          description: Created time for this bookshelf (formatted UTC timestamp with millisecond resolution)
          example: "2023-01-15T10:30:00.000Z"
        volumeCount:
          type: integer
          description: Number of volumes in this bookshelf
          example: 42
        volumesLastUpdated:
          type: string
          format: date-time
          description: Last time a volume was added or removed from this bookshelf (formatted UTC timestamp with millisecond resolution)
          example: "2024-01-15T10:30:00.000Z"
    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"
  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
tags:
  - name: Bookshelves
  - name: My Library
  - name: Volumes