ONIX 3.0 for Google Play Books

Specifies the encoding for the XML file, which should be UTF-8.

When to include: Required.

Specifies the document structure. Note that without release="3.0", the file will be interpreted as being ONIX 2.1 and will not validate.

When to include: Either XML Schema or DTD required.

This tag encloses the below information about your file.

When to include: Required.

Information about the entity sending the file.

Type: Composite.

When to include: Required.

The name of the entity sending the file.

When to include: Required.

Name of contact person at sending entity.

When to include: Recommended.

Email address of contact at sending entity.

When to include: Recommended.

Information about the entity to which the ONIX file is being sent.

Type: Composite.

When to include: Optional.

Name of the entity to which the ONIX file is being sent.

When to include: Optional.

Specifies the date and time when the file is being sent -- this field is used to apply the most recent metadata update to your book. Must include year, month and day. May optionally include hour (on a 24-hour clock), minutes, and seconds, which is recommended when sending more than one file per date.

When to include: Required.

Specifies the currency to use for <Price> composites when currency isn't otherwise supplied. Please see the section on ONIX in the article "Currency conversion for books on Google Play" for full details on how to supply prices in different currencies with ONIX.

When to include: Optional.

This tag encloses the following information about your book.

Type: Composite, repeatable.

When to include: Required for each book in the file; at least one <Product> tag should be included per file.

The Record Reference is a unique, permanent identifier not for the Product itself, but rather for the information record about the Product. The Record Reference is used to match up with previously received Product records.

When to include: Required exactly once for each product record.

The type of notification being provided for the product.

Providing a value of 05 will deactivate the book in Google Play and Google Book Search.

When to include: Required exactly once for each product record.

Type: Composite, repeatable.

When to include: Required at least once for each <Product> or <RelatedProduct> composite.

ONIX code specifying the Product Identifier type provided.

When to include: Required exactly once per <ProductIdentifier> composite.

When to include: Required exactly once per <ProductIdentifier> composite.

Describes the product form and metadata such as title, content description, and authorship.

Type: Composite.

When to include: Required exactly once per <Product> composite.

Indicates when the product is composed of a single or multiple items.

When to include: Required exactly once per <DescriptiveDetail> composite.

Indicates the primary form of the book.

When to include: Required exactly once per <DescriptiveDetail> composite. If the <ProductForm> is not one of EA, EB, EC, ED, the record will not be used to create an entry in the Partner Center, and its prices will not be ingested.

Specifies the ebook format.

When to include: Required when specifying a digital <ProductForm> such as ED

This repeatable tag encloses the collection information of which your book belongs. 

Type: Composite, repeatable.

When to include: Recommended for each <DescriptiveDetail> composite if the book belongs in a collection.

The type of collection to which the product belongs. 

When to include: Required exactly once for each collection record.

Type: Composite, repeatable.

When to include: Required at least once for each <Collection>  composite.

ONIX code specifying the Product Identifier type provided.

When to include: Required exactly once per <CollectionIdentifier> composite.

When to include: Required exactly once per <CollectionIdentifier> composite.

This repeatable tag encloses the title information about your book.

Type: Composite, repeatable.

When to include: Required at least once for each <DescriptiveDetail> composite.

Indicates the type of the title.

When to include: Type 01 is required for each book in the file; other additional types (specified in separate instances of <TitleDetail> are optional.

A repeatable group of elements representing the title element.

Type: Composite, repeatable.

When to include: Required at least once for each <TitleDetail> composite.

The level of the title element. <TitleElement> composities with <TitleElementLevel> of 02 will be considered the series name.

When to include: Required exactly once per <TitleElement> composite.

Used to determine the part number of a product within a collection.

When to include: Use in conjunction with <TitleElementLevel>01<TitleElementLevel> to denote the part number in the collection. Use <TitleElementLevel>02<TitleElementLevel> to set the collection title. 

The text of the title itself.

When to include: Required exactly once for each <TitleElement> composite.

This repeatable composite tag encloses the contributor (author) information about your book.

Type: Composite, repeatable.

When to include: Required at least once for each <DescriptiveDetail> composite.

Used to determine the preferred order for displaying contributors.

When to include: Required if more than one contributor provided in the same <DescriptiveDetail> composite.

Repeatable tag describing the role of the contributor. Type A01 is required for each book in the file; any other additional types are optional and may be displayed on Book detail pages. Authors are surfaced on the Google Play Store book detail page and other contributor  types are displayed on the Google Books Search detail page.

Type: Repeatable.

When to include: Required at least once for each <Contributor> composite.

The name of the person who is a contributor.

When to include: Required exactly once per <Contributor> composite.

Biographical note about a contributor.

When to include: Recommended. Repeatable if the same biographical note is provided in multiple languages, specified by the language attribute.

Type of edition or version; repeatable if multiple values apply.

When to include: Recommended if one of the values applies.

Specifies the language of the text or, for translations, the language of the original work.

Type: Composite, repeatable.

When to include: Recommended for non-English books.

When to include: Required exactly once per <Language> composite.

ISO code indicating the language.

When to include: Required exactly once per <Language> composite.

Used to supply the number of pages.

Type: Composite.

When to include: Recommended.

Specifies the extent type.

When to include: Required exactly once per <Extent> composite.

The number of pages for this Extent Type Code.

When to include: Required exactly once per <Extent> composite.

Unit used for <ExtentValue>.

When to include: Required exactly once per <Extent> composite.

This repeatable composite tag encloses the following subject information about your book.

Type: Composite, repeatable.

When to include: Recommended.

An empty element that identifies the main subject category.

When to include: Recommended for the main subject when multiple instances of <Subject> with the same subject scheme are present.

The subject scheme used.

When to include: Required exactly once per <Subject> composite.

The subject or genre of the book.

When to include: Required exactly once per <Subject> composite.

Repeatable composite tag about the intended audience of the book.

Type: Composite, repeatable.

When to include: Recommended.

Identifies the scheme used for specifying the audience.

When to include: Required exactly once per <Audience> composite.

Specifies the audience, according to the scheme in <AudienceCodeType>

When to include: Required exactly once per <Audience> composite.

Composite describing the audience or readership range. An example is provided below.

When to include: Recommended.

ONIX code specifying how <AudienceRange> is measured (e.g., by age, by school grade, etc.).

When to include: Required exactly once per <AudienceRange> composite.

The precision of the value specified in the following <AudienceRangeValue>.

When to include: Required at least once per <AudienceRange> composite. A second occurrence is allowed if the <AudienceRange> contains a From value and a To value (see the example below).

Value of the range of specified in the <AudienceRange> composite.

When to include: Required at least once per <AudienceRange> composite. A second occurrence is allowed if the <AudienceRange> contains a From value and a To value (see the example below).

Provides additional marketing material for the book, including summary, description, review quotes, etc.

Partly replaces <OtherText> in ONIX 2.1.

Type: Composite.

When to include: Recommended.

Repeatable group describing a piece of textual content which provides additional marketing details about the book.

When to include: Recommended.

For book descriptions, Google recommends providing a <TextContent> composite with <TextType> of 02 or 03 for each book. Only one description is displayed if more than one is provided, prioritizing 03 (Description) over 02 (Short description/annotation).

Google also recommends providing a <TextContent> composite with <TextType> of 12 (Biographical note) for each book.

ONIX code specifying what type of text is provided.

When to include: Required exactly once per <TextContent> composite.

ONIX code specifying the intended audience for the text.

Type: Repeatable.

When to include: Required at least once per <TextContent> composite.

Actual text for <TextContent> composite.

When to include: Required at least once for each <TextContent> composite. Repeatable when the same text is provided in multiple languages, specified by the language attribute (see Code List 74, ISO 639-2/B for language codes).

Name of the author of the text.

When to include: Optional.

Source of the text.

When to include: Optional.

Information about a date associated with the collateral text.

Type: Composite, repeatable.

When to include: Optional.

An ONIX code indicating the significance of the Content Date.

When to include: Required exactly once per <ContentDate> composite.

The date associated with the text.

When to include: Required exactly once per <ContentDate> composite.

Used to describe chapters or other parts in a structured way.

Type: Composite.

When to include: Recommended.

Repeatable element for each item within <ContentDetail>.

Type: Composite, repeatable.

When to include: Required at least once for each <ContentDetail> composite.

Composite containing information for the text item.

Type: Composite.

When to include: Required exactly once for each <ContentItem> composite.

When to include: Required exactly once for each <TextItem> composite.

The number of pages of text described by the enclosing <TextItem>.

When to include: Optional; up to one per <TextItem> composite.

Composite containing publisher, imprint, and publishing status details.

Type: Composite.

When to include: Required for <NotificationType> values 01, 02, and 03.

Repeatable group which carries the imprint name.

Type:Composite, repeatable.

When to include: Optional

When to include: Required exactly once per <Imprint>.

Repeatable group describing the entity acting as publisher for this book.

Type: Composite, repeatable.

When to include: Recommended

ONIX code identifying the publisher's role.

When to include: Required exactly once per <Publisher> composite.

Name of the publishing entity.

When to include: Required eactly once per <Publisher> composite.

Denotes publishing status, not product availability; supplies the global status, irrespective of geographical market. When the  book goes on sale is controlled by the <PublishingDate> inside a <PublishingDetail> composite or a  territory-specific <MarketPublishingDetail> composite, rather than the publishing status.

When to include: Required when not sending separate publishing statuses per market region.

Global date of publication.

Type: Composite, repeatable.

When to include: A <PublishingDate> composite with at least <PublishingDateRole> value of 01 is required. Additional market-specific publishing dates can be specified in <MarketPublishingDetail>.

ONIX code indicating what type of publishing date is provided.

Use a <PublishingDate> composite with a <PublishingDateRole> with a value of 02 (Embargo Date) to prevent your book from going on sale until the day specified in the enclosed <Date>.

When to include: Required exactly once per <PublishingDate> composite.

The date specified in <PublishingDateRole>.

When to include: Required exactly once per <PublishingDate> composite.

Repeatable group specifying sales rights per territory.

Type: Composite, repeatable.

When to include: Required for a book to be available for sale on the Google Play store.

ONIX code indicating the type of sales rights being described

When to include: Required exactly once per <SalesRights> composite.

Group describing the territory for which sales rights are being specified.

Type: Composite.

When to include: Required exactly once per <SalesRights> composite.

List of countries included in this territory; successive countries should be separated by spaces.

When to include: Either <CountriesIncluded> or <RegionsIncluded> is required exactly once per <Territory> composite.

List of regions included in territory; successive regions should be separated by spaces

When to include: Either <CountriesIncluded> or <RegionsIncluded> is required exactly once per <Territory> composite.

List of countries excluded from the territory; successive countries should be separated by spaces.

When to include: Optional.

List of regions excluded; successive regions should be separated by spaces

When to include: Optional.

Used to specify the sales rights type for countries or territories not specifically listed in a <SalesRightsType> composite.

When to include: Optional.

Provides references to related products (e.g. the print version of a digital book). Non-repeatable.

Type: Composite.

When to include: Recommended.

Repeatable group which describes a single related product.

Type:Composite, repeatable.

When to include: Recommended.

Repeatable ONIX code which specifies how the product is related.

Type: Repeatable.

When to include: Required at least once per <RelatedProduct> composite.

Type: Composite, repeatable.

When to include: Required at least once for each <Product> or <RelatedProduct> composite.

ONIX code specifying the Product Identifier type provided.

When to include: Required exactly once per <ProductIdentifier> composite.

When to include: Required exactly once per <ProductIdentifier> composite.

ONIX code specifying the form of the related product -- should match the <ProductForm> specified for the main <Product> record with the same ID as specified in this <RelatedProduct> record.

When to include: Optional.

ONIX code specifying the form detail of the related product -- should match the <ProductForm> specified for the main <Product> record with the same ID as specified in this <RelatedProduct> record.

When to include: Optional.

Specifies product supply details per market.

Type: Composite, repeatable.

When to include: Required to sell books on Google Play.

Specifies the geographical territory where the product supply details apply.

Type: Composite, repeatable.

When to include: Required.

Group describing the territory for which sales rights are being specified.

Type: Composite.

When to include: Required exactly once per <SalesRights> composite.

List of countries included in this territory; successive countries should be separated by spaces.

When to include: Either <CountriesIncluded> or <RegionsIncluded> is required exactly once per <Territory> composite.

List of regions included in territory; successive regions should be separated by spaces

When to include: Either <CountriesIncluded> or <RegionsIncluded> is required exactly once per <Territory> composite.

List of countries excluded from the territory; successive countries should be separated by spaces.

When to include: Optional.

List of regions excluded; successive regions should be separated by spaces

When to include: Optional.

Specifies publishing details per market.

Type: Composite.

When to include: Should be provided for publishing details specific to the given market when those details do not match the onces given in the global <PublishingDetail> composite.

Specifies publishing status details per market.

When to include: Required exactly once per <MarketPublishingDetail> composite.

Specifies a date associated with the market publishing detail. See the global <PublishingDate> composite for an example of how to provide an embargo date.

Type: Composite.

When to include: Optional.

Significance of the date.

When to include: Required exactly once per <MarketDate> composite.

The date associated with the Market Publishing Detail.

When to include: Required per <MarketDate> composite.

Repeatable composite containing information about a product's supply, source, availability, and price.

Type: Composite, repeatable.

When to include: Required at least once per <ProductSupply> composite.

Information about the supplier.

Type: Composite.

When to include: Required at least once per <SupplyDetail>.

ONIX code specifying the role that the supplier plays.

When to include: Required exactly once per <Supplier> composite.

The supplier name.

When to include: Required.

ONIX code specifying the product availability from the supplier.

When to include: Required exactly once per <SupplyDetail>.

ONIX code specifying products that are free of charge, products where a price has not yet been announced, or products where no price is applicable. In particular, for free of charge products, <UnpricedItemType> 01 should always be used in place of a <Price> composite where the Price amount is zero.

When to include: Required exactly once per <SupplyDetail>.

Specifies a date associated with the <SupplyDetail>.

Type: Composite, repeatable.

When to include: Optional.

Significance of the Supply Date.

When to include: Required exactly once per <SupplyDate> composite.

The date associated with the Supply Detail.

When to include: Required exactly once per <SupplyDate> composite.

Specifies a unit price; required for a book to be available for sale.

See our article on currency conversion for help with prices and currencies.

Type: Composite.

When to include: Each <SupplyDetail> must contain either one or more <Price> composites.

When to include: Required exactly once per <Price> composite.

Example: For a book with a listed price of 7.99€, and the following sales territory configuration in the Payment Center:

• "WORLD", with the default recommended price setting.
• "DE,AT" (by way of example only), with a fixed-price setting ("I'm subject to fixed pricing laws in these countries" checkbox, accessible by clicking Edit next to the sales territory).

Specify additional information about the price type.

When to include: Optional.

Amount in specified currency; do not specify a price of 0.00.

When to include: Required exactly once per <Price>.

Specifies the currency for which <PriceAmount> is supplied.

When to include: Required exactly once per <Price> composite, unless <DefaultCurrencyCode> is supplied.

Group describing the territory for which sales rights are being specified.

Type: Composite.

When to include: Required exactly once per <SalesRights> composite.

List of countries included in this territory; successive countries should be separated by spaces.

When to include: Either <CountriesIncluded> or <RegionsIncluded> is required exactly once per <Territory> composite.

List of regions included in territory; successive regions should be separated by spaces

When to include: Either <CountriesIncluded> or <RegionsIncluded> is required exactly once per <Territory> composite.

List of countries excluded from the territory; successive countries should be separated by spaces.

When to include: Optional.

List of regions excluded; successive regions should be separated by spaces

When to include: Optional.

Specifies a date associated with the price.

When to include: Optional.

Example: To create a promotional price of USD 4.99 that is limited to the U.S., will be in effect from December 21st, 2015, through January 2nd, 2016, send the below. The price in the U.S. will be as shown on the following dates:

• December 20th, 2015: USD 9.99
• December 21st, 2015: USD 4.99
• January 2nd, 2016: USD 4.99
• January 3rd, 2016: USD 9.99

<!-- Specify the current non-promotional price for U.S. only -->
<Price>
  <PriceType>02</PriceType>
  <PriceAmount>9.99</PriceAmount>
  <CurrencyCode>USD</CurrencyCode>
  <Territory>
    <CountriesIncluded>US</CountriesIncluded>
  </Territory>
  <PriceDate>
    <PriceDateRole>14</PriceDateRole>
    <Date dateformat="00">20151101</Date>
  </PriceDate>
  <PriceDate>
    <PriceDateRole>15</PriceDateRole>
    <Date dateformat="00">20151220</Date>
  </PriceDate>
</Price>

<!-- Specify the promotional price from the start date to the end date, inclusive. -->
<Price>
  <PriceType>02</PriceType>
  <PriceAmount>4.99</PriceAmount>
  <CurrencyCode>USD</CurrencyCode>
  <Territory>
    <CountriesIncluded>US</CountriesIncluded>
  </Territory>
  <PriceDate>
    <PriceDateRole>14</PriceDateRole>
    <Date dateformat="00">20151221</Date>
 </PriceDate>
 <PriceDate>
    <PriceDateRole>15</PriceDateRole>
    <Date dateformat="00">20160102</Date>
  </PriceDate>
</Price>

<!-- Specify the return to the non-promotional price. -->
<Price>
  <PriceType>02</PriceType>
  <PriceAmount>9.99</PriceAmount>
  <CurrencyCode>USD</CurrencyCode>
  <Territory>
    <CountriesIncluded>US</CountriesIncluded>
  </Territory>
  <PriceDate>
    <PriceDateRole>14</PriceDateRole>
    <Date dateformat="00">20160103</Date>
  </PriceDate>
</Price>

<!-- Specify a price for a different territory with no promotion. -->
<Price>
  <PriceType>02</PriceType>
  <PriceAmount>5.00</PriceAmount>
  <CurrencyCode>EUR</CurrencyCode>
  <Territory>
    <CountriesIncluded>FR</CountriesIncluded>
  </Territory>
</Price>

Specifies if this is a start date or end date. Both are inclusive and based on the purchaser's time zone.

When to include: Required exactly once per <PriceDate> composite.

The date associated with the price.

When to include: Required exactly once per <PriceDate> composite.