Google My Library API

openapi: 3.1.0
info:
  title: Google Books About My Library 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: My Library
paths:
  /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:
    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'
    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'
    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'
    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
    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: 

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google/refs/heads/main/openapi/google-my-library-api-openapi.yml