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.

Commencer

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:

Book entity

While the full definition of Book is available at
schema.org/Book, you
only need to consider the following properties. You must define the required properties for
every book you choose to include in your feed. You can also define recommended properties to
add more information about your content, which can provide a better user experience.

Book (Work)

This Book entity is the top level entity type. It represents a work.

The Google-supported properties are the following:

Book (Edition)

The workExample property uses this Book entity. It represents an
edition of a work.

The Google-supported properties are the following:

Example Book (Edition):

Example Book (Edition) with multiple workExample properties:

Person ou Organization (author)

The author property of the book uses the
Person ou Organization entity.

Example author:

Example with multiple author properties:

PropertyValue (identifier)

The identifier property of the Edition uses the PropertyValue
entity.

Example identifier:

Example with multiple identifier properties:

Example ReadAction Book feed JSON file

Example BorrowAction Book feed JSON file

ReadAction (potentialAction)

The potentialAction property uses the ReadAction entity.
ReadAction defines your deep links to access the book, the retailer that stocks
the book, and the criteria that the users must meet. Criteria might include membership status,
login status, location, or anything else required to access the book.

Example ReadAction:

Example ReadAction with multiple EntryPoint properties:

BorrowAction (potentialAction)

The potentialAction property uses the BorrowAction entity.
BorrowAction defines your deep links to access the book, the library that stocks
the book, and the criteria that the users must meet. Criteria might include membership status,
login status, location, or anything else required to access the book.

Example BorrowAction:

Example BorrowAction with multiple EntryPoint properties:

Library entity

While the full definition of Library is available at
schema.org/Library,
you only need to consider the following properties. You must define the
required properties for every library you choose to include in your feed.
You can also define recommended properties to add more information about
your content, which can provide a better user experience.

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

The Library feed is distinct from the Book feed. Therefore, any Library
feed you might implement must be entirely separate from your Book feed.
For more information, refer to
Create your feed.

LibrarySystem

The LibrarySystem entity represents a collaborative network
of library members.

Library (member)

The member property of the LibrarySystem entity
uses the Library (member) entity.
Library (member) represents a single library member
of a given library system.

Example LibrarySystem feed JSON file