Book actions (Book) structured data

Book actions make Google Search an entry point to discover books and authors. This enables Search users to quickly buy or borrow the books that they find directly from Search results. For example, a user can search for Charlotte's Web and be presented with results that allow them to buy or borrow the book. As a provider of books, you can provide a feed of data to Google with the structured data schema provided here. Our specification provides ReadAction to let users buy a book and BorrowAction to borrow a book.

Read actions and borrow actions, which are incorporated into the panels, display options to buy or borrow the book. Through links you provide, read actions and borrow actions send users directly from the knowledge panel and other Google surfaces to a book page on your website or app.

The order of providers in the knowledge panel is personalized and dynamic to each user. This means different users see different orderings, and the same user might see different orderings at different times. There are a variety of factors that affect a given ordering. For example, if a user clicks a given provider link in the knowledge panel often, that provider is more likely to be positioned higher in an ordering. There's no way to control the order.

Get started

To successfully implement Book actions, you must build your feed in accordance with the Book actions structured data type definitions, but first review the following sections:

• Guidelines
• Create your feed
• Test your feed with the Data Feed validation tool
• Host your feed file
• Submit your feed file for review
• Update your feed as needed

Guidelines

To ensure that your books can be reliably surfaced in Search, it's important that you're familiar with some important details and key concepts. Further, your feed must meet some standardized format specifications.

To help you do that, follow the guidelines described here, in addition to the general structured data guidelines and the Search Essentials. The guidelines are as follows:

• Works and editions
• Library systems and library members
• ISBN and other supported identifiers
• Links

Works and editions

Throughout this documentation, we use two distinct terms when we talk about a book:

• Work: The abstract concept of a book. Specifically, metadata such as the title, author, and original language are attributes for a work.
• Edition: A concrete copy of the book. Specifically, metadata such as the year of publication, name of the edition, and International Standard Book Number (ISBN) are attributes for the edition.

For example, Charlotte's Web is a work, but every single variety it comes in is an edition. In this case, the work Charlotte's Web might have a first edition, second edition, abridged edition, French translation edition, and so on.

This distinction is especially important in the feed where it might not be immediately obvious. There are two Book entities:

• Book (Work) is the "top level" Book entity:
  • workExample is a property of Work and specifies one and only one instance of a Book (Edition).
  • There must be at least one workExample for each Work.
• Book (Edition) is the "lower level" Book entity.

It helps to remember that there can be multiple editions of a work. We recommend that you group these editions together as much as possible. This helps Google systems leverage all of the relevant information about a book and surface it in Search. If you must, you can break them into multiple work records, but each work record must have the following:

• A different @id.
• At least one edition with an ISBN or other supported identifier.

Library systems and library members

The Library entity is the "top level" Library entity type. It's an abstract construct, which consists of a LibrarySystem entity and each "lower level" Library (member) entity of that library system.

The LibrarySystem entity is an abstraction and represents a collaborative network of library members. For example, Austin Public Library can be specified as a LibrarySystem entity. The Austin Public Library website describes themself as a public library system that serves Austin, Texas. It consists of their 20 affiliated libraries, or library members.

Every LibrarySystem entity requires at least one Library (member) entity, even if in real life the library isn't part of any library system. In this scenario, for the purpose of Book action implementation, the library is the sole library member of its own library system. For the purpose of Book action implementation, unlike a library system, a library member isn't an abstraction and therefore has a physical address.

Conversely, every Library (member) entity must belong to at least one LibrarySystem entity.

ISBN and other supported identifiers

The ISBN is the main reconciliation signal when Google Search matches your feed data to Google's data. You must provide an ISBN or other supported identifier for all the books you wish to have surfaced in Search results. Without it, it's likely that your books can't be matched and therefore won't be served.

Google Search prefers ISBN-13, but you can alternatively provide the following:

• Online Computer Library Center (OCLC) Number
• Library of Congress Control Number (LCCN)
• JP e-code

Links

To make sure people have the best experience finding your books, links in your feed must adhere to the following guidelines:

• If you have duplicate pages for the same content, the link must be the canonical URL that contains the book title and other book information.
• After a user clicks a read action or borrow action link, the user must be sent to a page that directly supports the purchase or borrowing of the book. Specifically, don't point action links to pages with more links that must be clicked in order to purchase or borrow the content. For example, don't send people to a search results page or a product summary page.

Create your feed

If your site sells books for users to buy, you must upload your Book feed. A Google support team will reach out to you with details about how and where to upload your feed.

If your site lends books for users to borrow, you must upload two separate feeds: your Book feed and your Library feed. A Google support team will reach out to you with details about how and where to upload your feed.

Adhere to feed file size, quantity, and format requirements

The requirements are as follows:

• Feed file size requirements:
  • An uncompressed feed file's size must be less than 1 GB.
  • A feed file that's to be compressed must be less than 1 GB. If your uncompressed feed file exceeds 1 GB, you must split the uncompressed feed file into multiple files.
• You can compress feed files. They must be formatted into a zip, gz, tar, tar.gz, JAR, ar, arj, cpio, or dump archive file.
• If you have multiple feed files, you can upload them as is, or if you prefer, you can include them as part of a sitemap index file.
• Single feed files must have the .json filename extension.

Adhere to feed content requirements

Be especially aware of the following feed content requirements that you must adhere to:

• The feed mustn't contain stale entities. Stale entities are entities with availabilityEnds set to a date that has passed or entities that are no longer available on your site.
• All deep links, such as urlTemplate, and all URLs, such as url, that you include in your feed must be production URLs. Don't use QA, development, or any other type of non-production URL.
• All URLs, such as url, must be canonical.
• Each entity in your feed must specify the following properties:
  • A unique ID: @id
  • A unique URL: url
  • A unique deep link: urlTemplate

Test your feed with the Data Feed validation tool

We recommend the following troubleshooting steps for resolving common errors and warnings on the Data Feed validation tool:

• Make sure that you have the correct option selected in the Validate on field. Select Books Action for the Book entity.

• Verify that the value of @type is spelled correctly.
• Make sure that the value of @context is set properly. Set "@context": "https://schema.org" for both ReadAction and BorrowAction.

Host your feed file

When your feed file is ready, host it at a secure location. Google fetches the feed regularly to ensure that your content is up-to-date.

Host methods

The following feed hosting methods are supported:

Submit your feed file for review

For your content to be available on Google Search, a Google support team reviews the quality of the deep links in your feed. We strongly recommend that you manually test some of the deep links to confirm whether they open the page where users can buy or borrow the books.

To request a review of your feed, provide the following:

• Host location: The URL of your feed file.
• Host authentication, if applicable: The authentication credentials to allow Google to get the feed file from your host location.

Update your feed as needed

We recommend that you update your feed daily, but this ultimately depends on how often your catalog changes. Be aware of the following conditions and tips:

• Google Search doesn't support real-time updates.
• Google Search fetches your feed once a day and typically indexes the content within two days.
• If there's a foreseeable change in an edition's availability, use availabilityStarts and availabilityEnds to set the exact dates. If the entity is no longer available, remove the entity completely

Structured data type definitions

You must include the required properties listed here for your content to be eligible for display in structured search results. You can also include the recommended properties to add more information about your content, which can provide a better user experience.

DataFeed entity

Every schema.org data feed file delivered to Google must contain one single entity of DataFeed at the root level. All Book and Library entities must be listed under the dataFeedElement field of the DataFeed entity.

The Google-supported properties are the following:

{
  "@context": "https://schema.org",
  "@type": "DataFeed",
  "dataFeedElement": [
    {
      "@context": "https://schema.org",