Google Books Onboarding API

openapi: 3.1.0
info:
  title: Books API Onboarding API
  version: v1
  description: Generated from Google's published Discovery document for Books API (books v1, revision 20261105). 2 operation(s).
  contact:
    name: Google
    url: https://developers.google.com/
  termsOfService: https://developers.google.com/terms
externalDocs:
  url: https://code.google.com/apis/books/docs/v1/getting_started.html
servers:
- url: https://books.googleapis.com
paths:
  /books/v1/onboarding/listCategories:
    get:
      operationId: books.onboarding.listCategories
      summary: List categories onboarding
      description: List categories for onboarding experience.
      parameters:
      - name: locale
        in: query
        required: false
        description: ISO-639-1 language and ISO-3166-1 country code. Default is en-US if unset.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        4XX:
          content: &id001
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content: *id001
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/books
      - apiKey: []
      tags:
      - Onboarding
  /books/v1/onboarding/listCategoryVolumes:
    get:
      operationId: books.onboarding.listCategoryVolumes
      summary: List category volumes onboarding
      description: List available volumes under categories for onboarding experience.
      parameters:
      - name: categoryId
        in: query
        required: false
        description: List of category ids requested.
        schema:
          type: array
          items:
            type: string
      - name: locale
        in: query
        required: false
        description: ISO-639-1 language and ISO-3166-1 country code. Default is en-US if unset.
        schema:
          type: string
      - name: maxAllowedMaturityRating
        in: query
        required: false
        description: The maximum allowed maturity rating of returned volumes. Books with a higher maturity rating are filtered
          out.
        schema:
          type: string
          enum:
          - MAX_ALLOWED_MATURITY_RATING_UNDEFINED
          - MATURE
          - not-mature
      - name: pageSize
        in: query
        required: false
        description: Number of maximum results per page to be included in the response.
        schema:
          type: integer
          format: uint32
      - name: pageToken
        in: query
        required: false
        description: The value of the nextToken from the previous page.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volume2'
        4XX:
          content: &id002
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content: *id002
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/books
      - apiKey: []
      tags:
      - Onboarding
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: API key; accepted by methods that do not need user data.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/books: Manage your books
  schemas:
    Category:
      properties:
        items:
          items:
            type: object
            properties:
              badgeUrl:
                type: string
              categoryId:
                type: string
              name:
                type: string
          description: A list of onboarding categories.
          type: array
        kind:
          description: Resource type.
          type: string
      type: object
    DownloadAccessRestriction:
      type: object
      properties:
        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).
        nonce:
          description: Client nonce for verification. Download access and client-validation only.
          type: string
        source:
          description: Client app identifier for verification. Download access and client-validation only.
          type: string
        maxDownloadDevices:
          description: If restricted, the maximum number of content download licenses for this volume.
          type: integer
          format: int32
        volumeId:
          description: Identifies the volume for which this entry applies.
          type: string
        reasonCode:
          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
          type: string
        downloadsAcquired:
          format: int32
          description: If restricted, the number of content download licenses already acquired (including the requesting client,
            if licensed).
          type: integer
        justAcquired:
          description: If deviceAllowed, whether access was just acquired with this request.
          type: boolean
        kind:
          description: Resource type.
          type: string
        signature:
          description: Response signature.
          type: string
        message:
          type: string
          description: Error/warning message.
    GoogleRpcError:
      type: object
      description: The error envelope every Google API returns.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            status:
              type: string
            details:
              type: array
              items:
                type: object
    ReadingPosition:
      type: object
      properties:
        gbTextPosition:
          type: string
          description: Position in a volume for text-based content.
        volumeId:
          description: Volume id associated with this reading position.
          type: string
        gbImagePosition:
          type: string
          description: Position in a volume for image-based content.
        updated:
          description: Timestamp when this reading position was last updated (formatted UTC timestamp with millisecond resolution).
          type: string
        pdfPosition:
          type: string
          description: Position in a PDF file.
        epubCfiPosition:
          description: Position in an EPUB as a CFI.
          type: string
        kind:
          description: Resource type for a reading position.
          type: string
    Review:
      properties:
        author:
          type: object
          properties:
            displayName:
              type: string
              description: Name of this person.
          description: Author of this review.
        kind:
          description: Resource type for a review.
          type: string
        content:
          description: Review text.
          type: string
        type:
          description: Source type for this review. Possible values are EDITORIAL, WEB_USER or GOOGLE_USER.
          type: string
        volumeId:
          description: Volume that this review is for.
          type: string
        source:
          description: Information regarding the source of this review, when the review is not from a Google Books user.
          properties:
            description:
              type: string
              description: Name of the source.
            url:
              description: URL of the source of the review.
              type: string
            extraDescription:
              type: string
              description: Extra text about the source of the review.
          type: object
        fullTextUrl:
          description: URL for the full review text, for reviews gathered from the web.
          type: string
        title:
          type: string
          description: Title for this review.
        date:
          type: string
          description: Date of this review.
        rating:
          description: Star rating for this review. Possible values are ONE, TWO, THREE, FOUR, FIVE or NOT_RATED.
          type: string
      type: object
    Volume:
      type: object
      properties:
        kind:
          description: Resource type for a volume. (In LITE projection.)
          type: string
        userInfo:
          properties:
            isPurchased:
              description: Whether or not this volume was purchased by the authenticated user making the request. (In LITE
                projection.)
              type: boolean
            isFamilySharingDisabledByFop:
              description: 'Deprecated: Replaced by familySharing.'
              type: boolean
            isFamilySharingAllowed:
              description: 'Deprecated: Replaced by familySharing.'
              type: boolean
            copy:
              properties:
                updated:
                  type: string
                allowedCharacterCount:
                  type: integer
                  format: int32
                limitType:
                  type: string
                remainingCharacterCount:
                  format: int32
                  type: integer
              type: object
              description: Copy/Paste accounting information.
            isUploaded:
              type: boolean
              description: Whether or not this volume was user uploaded.
            acquisitionType:
              description: How this volume was acquired.
              type: integer
              format: int32
            isInMyBooks:
              type: boolean
              description: Whether or not this volume is currently in "my books."
            review:
              $ref: '#/components/schemas/Review'
              description: This user's review of this volume, if one exists.
            entitlementType:
              type: integer
              description: Whether this volume is purchased, sample, pd download etc.
              format: int32
            readingPosition:
              $ref: '#/components/schemas/ReadingPosition'
              description: The user's current reading position in the volume, if one is available. (In LITE projection.)
            acquiredTime:
              description: Timestamp when this volume was acquired by the user. (RFC 3339 UTC date-time format) Acquiring
                includes purchase, user upload, receiving family sharing, etc.
              type: string
            isFamilySharedToUser:
              description: Whether or not the user received this volume through family sharing.
              type: boolean
            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
              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).
            userUploadedVolumeInfo:
              properties:
                processingState:
                  type: string
              type: object
            rentalPeriod:
              description: Period during this book is/was a valid rental.
              properties:
                endUtcSec:
                  type: string
                  format: int64
                startUtcSec:
                  type: string
                  format: int64
              type: object
            familySharing:
              type: object
              properties:
                isSharingDisabledByFop:
                  type: boolean
                  description: Whether or not sharing this volume is temporarily disabled due to issues with the Family Wallet.
                familyRole:
                  description: The role of the user in the family.
                  type: string
                isSharingAllowed:
                  description: Whether or not this volume can be shared with the family by the user. This includes sharing
                    eligibility of both the volume and the user. If the value is true, the user can initiate a family sharing
                    action.
                  type: boolean
              description: Information on the ability to share with the family.
            rentalState:
              description: Whether this book is an active or an expired rental.
              type: string
            isFamilySharedFromUser:
              type: boolean
              description: Whether or not the user shared this volume with the family.
          description: User specific information related to this volume. (e.g. page this user last read or whether they purchased
            this book)
          type: object
        layerInfo:
          description: What layers exist in this volume and high level information about them.
          type: object
          properties:
            layers:
              description: A layer should appear here if and only if the layer exists for this book.
              type: array
              items:
                type: object
                properties:
                  volumeAnnotationsVersion:
                    description: The current version of this layer's volume annotations. Note that this version applies only
                      to the data in the books.layers.volumeAnnotations.* responses. The actual annotation data is versioned
                      separately.
                    type: string
                  layerId:
                    description: The layer id of this layer (e.g. "geo").
                    type: string
        accessInfo:
          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.).
          type: object
          properties:
            downloadAccess:
              $ref: '#/components/schemas/DownloadAccessRestriction'
              description: Information about a volume's download license access restrictions.
            pdf:
              properties:
                acsTokenLink:
                  type: string
                  description: URL to retrieve ACS token for pdf download. (In LITE projection.)
                downloadLink:
                  description: URL to download pdf. (In LITE projection.)
                  type: string
                isAvailable:
                  description: Is a scanned image pdf available either as public domain or for purchase. (In LITE projection.)
                  type: boolean
              type: object
              description: Information about pdf content. (In LITE projection.)
            accessViewStatus:
              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.)
              type: string
            quoteSharingAllowed:
              description: Whether quote sharing is allowed for this volume.
              type: boolean
            webReaderLink:
              description: URL to read this volume on the Google Books site. Link will not allow users to read non-viewable
                volumes.
              type: string
            publicDomain:
              type: boolean
              description: Whether or not this book is public domain in the country listed above.
            viewOrderUrl:
              description: For ordered but not yet processed orders, we give a URL that can be used to go to the appropriate
                Google Wallet page.
              type: string
            embeddable:
              description: Whether this volume can be embedded in a viewport using the Embedded Viewer API.
              type: boolean
            viewability:
              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.
              type: string
            textToSpeechPermission:
              type: string
              description: Whether text-to-speech is permitted for this volume. Values can be ALLOWED, ALLOWED_FOR_ACCESSIBILITY,
                or NOT_ALLOWED.
            epub:
              properties:
                isAvailable:
                  description: Is a flowing text epub available either as public domain or for purchase. (In LITE projection.)
                  type: boolean
                downloadLink:
                  type: string
                  description: URL to download epub. (In LITE projection.)
                acsTokenLink:
                  description: URL to retrieve ACS token for epub download. (In LITE projection.)
                  type: string
              description: Information about epub content. (In LITE projection.)
              type: object
            driveImportedContentLink:
              description: URL to the Google Drive viewer if this volume is uploaded by the user by selecting the file from
                Google Drive.
              type: string
            explicitOfflineLicenseManagement:
              type: boolean
              description: Whether this volume requires that the client explicitly request offline download license rather
                than have it done automatically when loading the content, if the client supports it.
            country:
              type: string
              description: The two-letter ISO_3166-1 country code for which this access information is valid. (In LITE projection.)
        recommendedInfo:
          type: object
          properties:
            explanation:
              description: A text explaining why this volume is recommended.
              type: string
          description: Recommendation related information for this volume.
        searchInfo:
          properties:
            textSnippet:
              description: A text snippet containing the search query.
              type: string
          description: Search result information related to this volume.
          type: object
        id:
          description: Unique identifier for a volume. (In LITE projection.)
          type: string
        volumeInfo:
          properties:
            canonicalVolumeLink:
              description: Canonical URL for a volume. (In LITE projection.)
              type: string
            publishedDate:
              description: Date of publication. (In LITE projection.)
              type: string
            categories:
              items:
                type: string
              description: A list of subject categories, such as "Fiction", "Suspense", etc.
              type: array
            title:
              description: Volume title. (In LITE projection.)
              type: string
            panelizationSummary:
              description: A top-level summary of the panelization info in this volume.
              properties:
                imageBubbleVersion:
                  type: string
                containsImageBubbles:
                  type: boolean
                containsEpubBubbles:
                  type: boolean
                epubBubbleVersion:
                  type: string
              type: object
            publisher:
              type: string
              description: Publisher of this volume. (In LITE projection.)
            infoLink:
              description: URL to view information about this volume on the Google Books site. (In LITE projection)
              type: string
            seriesInfo:
              $ref: '#/components/schemas/Volumeseriesinfo'
            readingModes:
              description: The reading modes available for this volume.
              properties:
                text:
                  type: boolean
                image:
                  type: boolean
              type: object
            pageCount:
              type: integer
              format: int32
              description: Total number of pages as per publisher metadata.
            printedPageCount:
              type: integer
              description: Total number of printed pages in generated pdf representation.
              format: int32
            maturityRating:
              type: string
            subtitle:
              description: Volume subtitle. (In LITE projection.)
              type: string
            language:
              description: Best language for this volume (based on content). It is the two-letter ISO 639-1 code such as 'fr',
                'en', etc.
              type: string
            contentVersion:
              type: string
              description: An identifier for the version of the volume content (text & images). (In LITE projection)
            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.
            dimensions:
              description: Physical dimensions of this volume.
              type: object
              properties:
                height:
                  description: Height or length of this volume (in cm).
                  type: string
                thickness:
                  description: Thickness of this volume (in cm).
                  type: string
                width:
                  description: Width of this volume (in cm).
                  type: string
            allowAnonLogging:
              type: boolean
              description: Whether anonymous logging should be allowed.
            printType:
              type: string
              description: Type of publication of this volume. Possible values are BOOK or MAGAZINE.
            comicsContent:
              description: Whether the volume has comics content.
              type: boolean
            samplePageCount:
              type: integer
              format: int32
              description: Total number of sample pages as per publisher metadata.
            ratingsCount:
              type: integer
              description: The number of review ratings for this volume.
              format: int32
            authors:
              description: The names of the authors and/or editors for this volume. (In LITE projection)
              type: array
              items:
                type: string
            previewLink:
              description: URL to preview this volume on the Google Books site.
              type: string
            imageLinks:
              description: A list of image links for all the sizes that are available. (In LITE projection.)
              type: object
              properties:
                small:
                  type: string
                  description: Image link for small size (width of ~300 pixels). (In LITE projection)
                large:
                  description: Image link for large size (width of ~800 pixels). (In LITE projection)
                  type: string
                thumbnail:
                  description: Image link for thumbnail size (width of ~128 pixels). (In LITE projection)
                  type: string
                extraLarge:
                  description: Image link for extra large size (width of ~1280 pixels). (In LITE projection)
                  type: string
                medium:
                  description: Image link for medium size (width of ~575 pixels). (In LITE projection)
                  type: string
                smallThumbnail:
                  type: string
                  description: Image link for small thumbnail size (width of ~80 pixels). (In LITE projection)
            averageRating:
              description: The mean review rating for this volume. (min = 1.0, max = 5.0)
              type: number
              format: double
            industryIdentifiers:
              type: array
              items:
                type: object
                properties:
                  identifier:
                    type: string
                    description: Industry specific volume identifier.
                  type:
                    description: Identifier type. Possible values are ISBN_10, ISBN_13, ISSN and OTHER.
                    type: string
              description: Industry standard identifiers for this volume.
            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.)
          description: General volume information.
          type: object
        selfLink:
          description: URL to this resource. (In LITE projection.)
          type: string
        saleInfo:
          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:
            buyLink:
              type: string
              description: URL to purchase this volume on the Google Books site. (In LITE projection)
            country:
              description: The two-letter ISO_3166-1 country code for which this sale information is valid. (In LITE projection.)
              type: string
            offers:
              items:
                type: object
                properties:
                  retailPrice:
                    description: Offer retail (=discounted) price in Micros
                    type: object
                    properties:
                      currencyCode:
                        type: string
                      amountInMicros:
                        format: double
                        type: number
                  listPrice:
                    description: Offer list (=undiscounted) price in Micros.
                    type: object
                    properties:
                      amountInMicros:
                        type: number
                        format: double
                      currencyCode:
                        type: string
                  finskyOfferType:
                    description: The finsky offer type (e.g., PURCHASE=0 RENTAL=3)
                    format: int32
                    type: integer
                  rentalDuration:
                    description: The rental duration (for rental offers only).
                    type: object
                    properties:
                      count:
                        type: number
                        format: double
                      unit:
                        type: string
                  giftable:
                    description: Indicates whether the offer is giftable.
                    type: boolean
              description: Offers available for this volume (sales and rentals).
              type: array
            saleability:
              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, FOR_RENTAL_ONLY, FOR_SALE_AND_RENTAL, FREE, NOT_FOR_SALE,
                or FOR_PREORDER.
              type: string
            onSaleDate:
              type: string
              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).
            retailPrice:
              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:
                  description: Amount in the currency listed below. (In LITE projection.)
                  type: number
                  format: double
                currencyCode:
                  type: string
                  description: An ISO 4217, three-letter currency code. (In LITE projection.)
              type: object
            listPrice:
              properties:
                amount:
                  type: number
                  format: double
                  description: Amount in the currency listed below. (In LITE projection.)
                currencyCode:
                  type: string
                  description: An ISO 4217, three-letter currency code. (In LITE projection.)
              type: object
              description: Suggested retail price. (In LITE projection.)
          type: object
        etag:
          description: Opaque identifier for a specific version of a volume resource. (In LITE projection)
          type: string
    Volume2:
      properties:
        kind:
          type: string
          description: Resource type.
        items:
          items:
            $ref: '#/components/schemas/Volume'
          description: A list of volumes.
          type: array
        nextPageToken:
          type: string
      type: object
    Volumeseriesinfo:
      properties:
        shortSeriesBookTitle:
          type: string
          description: Short book title in the context of the series.
        kind:
          type: string
          description: Resource type.
        volumeSeries:
          type: array
          items:
            type: object
            properties:
              orderNumber:
                format: int32
                type: integer
                description: The book order number in the series.
              issue:
                description: List of issues. Applicable only for Collection Edition and Omnibus.
                items:
                  properties:
                    issueOrderNumber:
                      format: int32
                      type: integer
                    issueDisplayNumber:
                      type: string
                  type: object
                type: array
              seriesBookType:
                description: The book type in the context of series. Examples - Single Issue, Collection Edition, etc.
                type: string
              seriesId:
                type: string
                description: The series id.
        bookDisplayNumber:
          description: The display number string. This should be used only for display purposes and the actual sequence should
            be inferred from the below orderNumber.
          type: string
      type: object
x-provenance:
  method: harvested
  publisher: Google
  source: https://books.googleapis.com/$discovery/rest?version=v1
  note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261105)