Document revision history

Date	Version
28 Mar 2023	v 3.6	Local ONIX best pratices Added: Content detail effective from 16 May 2023 Changed: the order of Local ONIX best practices topics to match the order in the ONIX Product record
13 Oct 2022	v 3.5	Added to ProductAvailability: Announcements, effective from 1 Dec 2022
24 Jan 2022	v 3.4	Cancel an order is no longer supported
16 Aug 2021	v3.3	Added to 5.3.7: RelatedProduct
08 Jun 2021	v3.2	Timezone: CET/CEST (= UTC+2) added at 4.2 Catalogue metadaata in ONIX 3 format - modifiedfrom
16 Feb 2021	v3.1	Major revision, chapters renumbered ONIX explanation added Reset download links explained New feature: order cancelation (in 7-day window) Reseller client dashboard updated References to Luisterhuis ProductID changed to EAN13 App API removed
22 Jun 2020	v3.0	Draft App API renamed Support for Ecosystem clients removed, now in separate document
01 Oct 2019	v2.8	New v3 endpoints to replace v2 endpoints Changes in default LIMIT and OFFSET values
02 May 2018	v2.7	Updated ONIX examples (chapter 4, chapter 12). Improved explanation Inventory API (chapter 4.3). Wrong chapter number references corrected.
26 Apr 2018	v2.6	Facetted search (chapter 4) deprecated and phased out. Removed from documentation.
18 Apr 2018	v2.5	New stub endpoints (stub-www replaces stub.www; stub-rest replaces stub.rest). New ONIX 3.0 /v2/feed endpoints added (Chapter 4). Please note: old endpoints will be phased out. Textual changes: settlement renamed to monthly settlement; extra explanation about different usage modes and business models. Usage API added (chapter 8)
01 Sep 2016	v2.4	Settlement API added (chapter 7) Textual changes Wrong URL in earlier documentation: all restful end points changed to rest.luisterhuis.nl
05 Mar 2016	v2.3	Textual changes
16 Feb 2016	v2.2	Support for retrieving metadata for all products in a single inventory call (chapter 4.4) Extra value 'CustomerID' in API call submitOrder (chapter 5.4) New features Luisterhuis portal for resellers (reactivate download link, csv download) Support for apps Support for Ecosystem clients Support for private content feeds Updated ONIX and XML examples
22 Apr 2015	v2.1	Support for NSTC (Dutch equivalent for ISTC) in ONIX 3 metadata Additional audiobook metadata (square images, update date/time images, mp3 files)
16 Aug 2010	v2.0	Rewritten documentation, now including description of 2 interface scenarios New API function: update by date Deprecated API function: send downloadlink by email removed from documentation
21 Jul 2010	v1.4	New API function: orders accepted by product ID or EAN13
04 Jun 2010	v1.3	New API function: send download link by email
31 May 2010	v1.2	Bug fixes
27 May 2010	v1.1	Stub (testing) environment added
06 May 2010	v1.0	First release

...

The following paragraphs describe the specific ONIX implementation and best practices for the Dutch market.

ProductForm and PrimaryContentType

For digital audiobooks, the following <ProductForm> is used:

Code Block

language	xml
title	ProductForm

<ProductForm>AJ</ProductForm>
<ProductFormDetail>A103</ProductFormDetail>
<PrimaryContentType>01</ PrimaryContentType>

The following values for <PrimaryContentType> are supported:

01 Audio (audiobook)
02 Performance (audio drama, theatre, cabaret)
03 Music Recording
04 Other Audio (nature sounds, soundscapes)
13 Other Speech Content (lectures, interviews, discussions, audio tours)

Title and collection

The ONIX metadata supports the following title and collection elements:

...

Expand

title	Click here for an example with collection

Code Block

language	xml

			<Collection>
				<CollectionType>10</CollectionType>
				<TitleDetail>
					<TitleType>01</TitleType>
					<TitleElement>
						<TitleElementLevel>02</TitleElementLevel>
						<PartNumber>5</PartNumber>
						<TitleText>Robert Langdon</TitleText>
					</TitleElement>
				</TitleDetail>
			</Collection>
			<TitleDetail>
				<TitleType>01</TitleType>
				<TitleElement>
					<TitleElementLevel>01</TitleElementLevel>
					<TitleText>Oorsprong</TitleText>
					<Subtitle>Auteur van De Da Vinci Code</Subtitle>
				</TitleElement>
			</TitleDetail>

Short and long description/annotation

The ONIX metadata contains two different descriptive texts for every audiobook: a short one (max. 200 characters, no HTML) and a long one (no limitations).

The short text (Short description/annotation) can be used for hitlists, SEO, mobile, social media, popups, alt-tags, and other situations where there is no space for a long text.

...

Contributor roles

Audiobook metadata supports the following contributor roles:

A01 Author of the work
E07 Read by (reader of recorded text)
B06 Translator (optionally)

PrefixToKey in contributor elements

In the Dutch language area <PrefixToKey> is used for all relevant contributor names (authors, narrators) with a typical Dutch prefix in their last name. For instance, the name ‘Dirkjan van Ittersum’ will be supplied in the ONIX as follows:

Code Block

language	xml
title	Short text

<TextContent>
   <TextType>02</TextType>
   <ContentAudience>00</ContentAudience>
   <Text><![CDATA[In 'Oorsprong' houdt Robert Langdon zich bezig met de vragen: Waar komen wij vandaan en waar gaan wij naartoe? Vol moderne kunst, innovatieve technologie, religie en geschiedenis.]]></Text>
   <ContentDate>
     <ContentDateRole>01</ContentDateRole>
     <Date dateformat="00">20171003</Date>
   </ContentDate>
</TextContent>

...

Contributor - PrefixToKey

<PersonName>Dirkjan van Ittersum</PersonName>
<NamesBeforeKey>Dirkjan</NamesBeforeKey>
<PrefixToKey>van</PrefixToKey>
<KeyNames>Ittersum</KeyNames>

It is the responsibility of the web shop to comply with this standard and parse the <PrefixToKey> field.

Abridged / unabridged

The ONIX contains the <EditionType> element which refers to either abridged (content has been shortened in relation to the original book) or unabridged content.

There are 2 possible values for <EditionType> supported:

ABR Abridged
UBR Unabridged

Language codes

All audiobooks contain the language code for the text <LanguageRole> 01 and spoken language <LanguageRole> 08, which are always identical. Most translated audiobooks also contain the language code for the original language <LanguageRole> 02.

Code Block

language	xml
title	Example for Dutch spoken audio book:

<Language>
 <LanguageRole>01</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>
<Language>
 <LanguageRole>08</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>

Code Block

language	xml
title	Example for Dutch spoken audiobook, translated from Swedish

<Language>
 <LanguageRole>01</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>
<Language>
 <LanguageRole>02</LanguageRole>
 <LanguageCode>swe</LanguageCode>
</Language>
<Language>
 <LanguageRole>08</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>

Duration and size values

The ONIX contains duration and size values of the audiobook files.

Code Block

language	xml
title	Long description

<TextContent>
  <TextType>03</TextType>
  <ContentAudience>00</ContentAudience>
  <Text textformat="02"><![CDATA[In Oorsprong van Dan Brown keert Robert Langdon weer terug om een van de grootste mysteries in zijn carrière op te lossen.

Robert Langdon, hoogleraar kunstgeschiedenis en symboliek, is te gast in het hypermoderne Guggenheim-museum in Bilbao, voor een belangrijke onthulling die de wetenschap voor altijd zal veranderen. De gastheer van de avond is Edmond Kirsch, een veertigjarige miljardair en futuroloog wiens oogverblindende hightech uitvindingen en gewaagde uitspraken hem wereldberoemd hebben gemaakt. Maar de zorgvuldig georkestreerde avond barst plotseling uit in chaos, waardoor Kirsch’ waardevolle ontdekking voorgoed dreigt te verdwijnen.
Samen met de elegante museumdirecteur Ambra Vidal vlucht Langdon naar Barcelona, waar ze een spoor volgen dat ze uiteindelijk oog in oog zal brengen met Kirsch’ schokkende
ontdekking…]]></Text>
</TextContent>

Contributor roles

Audiobook metadata supports the following contributor roles:

A01 Author of the work
E07 Read by (reader of recorded text)
B06 Translator (optionally)

PrefixToKey in contributor elements

...

Duration and size values

<Extent>
 <ExtentType>09</ExtentType>
 <ExtentValue>21287</ExtentValue>
 <ExtentUnit>06</ExtentUnit>
</Extent>
<Extent>
 <ExtentType>09</ExtentType>
 <ExtentValue>0055447</ExtentValue>
 <ExtentUnit>16</ExtentUnit>
</Extent>
<Extent>
 <ExtentType>22</ExtentType>
 <ExtentValue>197</ExtentValue>
 <ExtentUnit>19</ExtentUnit>
</Extent>

These are the supported types and units:

ExtentType

09 Duration (running time)
22 File size

ExtentUnit

06 seconds (integer value)
16 Hours minutes seconds (HHHMMSS)
19 Mbytes (integer value)

Subject metadata

The ONIX can contain up to four different subject elements: NUR (Dutch), BISAC (international), Thema (international) and keywords. All titles contain at least one NUR and one BISAC value. Thema values and keywords are optional. A growing number of titles will be supplied with Thema subject metadata.

ONIX elements

NUR

Code Block

language	xml
title	NUR

<Subject>
 <MainSubject/> <SubjectSchemeIdentifier>32</SubjectSchemeIdentifier>
 <SubjectCode>332</SubjectCode>
</Subject>

The NUR value of 332 is an example. The valid NUR range is 200 to 999. More info about NUR can be found here: https://www.isbn.nl/uploads/images/NUR-lijst-versie-2011.pdf
Multiple NUR values are supported. The main NUR subject has the tag <MainSubject/>.

BISAC

Code Block

language	xml
title	BISAC

<Subject>
  <MainSubject/>
  <SubjectSchemeIdentifier>10</SubjectSchemeIdentifier>
  <SubjectCode>HIS010020</SubjectCode>
</Subject>

Multiple BISAC values are supported. The main BISAC subject has the tag <MainSubject/>.

Thema

Code Block

language	xml
title	Thema

<Subject>
    <MainSubject/>
	<SubjectSchemeIdentifier>93</SubjectSchemeIdentifier>
	<SubjectSchemeVersion>1.3</SubjectSchemeVersion>
	<SubjectCode>FXM</SubjectCode>
</Subject>
<Subject>
	<SubjectSchemeIdentifier>93</SubjectSchemeIdentifier>
	<SubjectSchemeVersion>1.3</SubjectSchemeVersion>
	<SubjectCode>FBA</SubjectCode>
</Subject>
    <Subject>
	<SubjectSchemeIdentifier>94</SubjectSchemeIdentifier>
	<SubjectSchemeVersion>1.3</SubjectSchemeVersion>
	<SubjectCode>1KBB-US-WPC</SubjectCode>
</Subject>

The ONIX elements for Thema supports multiple values of the <SubjectSchemeIdentifier> 93, 94, 95, 96, 97 and 98.

Keywords

Code Block

language	xml
title	Keywords

<Subject>
 <SubjectSchemeIdentifier>20</SubjectSchemeIdentifier>
 <SubjectHeadingText>chicklit;dochtertje becky;engels;feel-good roman; 
rebecca bloomwood;shopaholic;sophie kinsella</SubjectHeadingText>
</Subject>

The ONIX element for Keywords uses <SubjectSchemeIdentifier> 20. Different keywords
are separated by a ; character.

Short and long description/annotation

The ONIX metadata contains two different descriptive texts for every audiobook: a short one (max. 200 characters, no HTML) and a long one (no limitations).

The short text (Short description/annotation) can be used for hitlists, SEO, mobile, social media, popups, alt-tags, and other situations where there is no space for a long text.

The ONIX element for short text is defined by <TextType> 02:

Code Block

language	xml
title	Contributor - PrefixToKey

<PersonName>Dirkjan van Ittersum</PersonName>
<NamesBeforeKey>Dirkjan</NamesBeforeKey>
<PrefixToKey>van</PrefixToKey>
<KeyNames>Ittersum</KeyNames>

It is the responsibility of the web shop to comply with this standard and parse the <PrefixToKey> field.

Subject metadata

The ONIX can contain up to four different subject elements: NUR (Dutch), BISAC (international), Thema (international) and keywords. All titles contain at least one NUR and one BISAC value. Thema values and keywords are optional. A growing number of titles will be supplied with Thema subject metadata.

...

Code Block

language	xml
title	NUR

<Subject>
 <MainSubject/> <SubjectSchemeIdentifier>32</SubjectSchemeIdentifier>
 <SubjectCode>332</SubjectCode>
</Subject>

...

Short text

<TextContent>
   <TextType>02</TextType>
   <ContentAudience>00</ContentAudience>
   <Text><![CDATA[In 'Oorsprong' houdt Robert Langdon zich bezig met de vragen: Waar komen wij vandaan en waar gaan wij naartoe? Vol moderne kunst, innovatieve technologie, religie en geschiedenis.]]></Text>
   <ContentDate>
     <ContentDateRole>01</ContentDateRole>
     <Date dateformat="00">20171003</Date>
   </ContentDate>
</TextContent>

The long description is defined by <TextType> 03:

Code Block

title
language	xml

...

Long description

...

<TextContent>

...

<TextType>03</

...

TextType>

...

<ContentAudience>00</

...

ContentAudience>

...

Code Block

language	xml
title	Thema

<Subject>
    <MainSubject/>
	<SubjectSchemeIdentifier>93</SubjectSchemeIdentifier>
	<SubjectSchemeVersion>1.3</SubjectSchemeVersion>
	<SubjectCode>FXM</SubjectCode>
</Subject>
<Subject>
	<SubjectSchemeIdentifier>93</SubjectSchemeIdentifier>
	<SubjectSchemeVersion>1.3</SubjectSchemeVersion>
	<SubjectCode>FBA</SubjectCode>
</Subject>
    <Subject>
	<SubjectSchemeIdentifier>94</SubjectSchemeIdentifier>
	<SubjectSchemeVersion>1.3</SubjectSchemeVersion>
	<SubjectCode>1KBB-US-WPC</SubjectCode>
</Subject>

...

Code Block

language	xml
title	Keywords

<Subject>
 <SubjectSchemeIdentifier>20</SubjectSchemeIdentifier>
 <SubjectHeadingText>chicklit;dochtertje becky;engels;feel-good roman; 
rebecca bloomwood;shopaholic;sophie kinsella</SubjectHeadingText>
</Subject>

...

Language codes

All audiobooks contain the language code for the text <LanguageRole> 01 and spoken language <LanguageRole> 08, which are always identical. Most translated audiobooks also contain the language code for the original language <LanguageRole> 02.

Code Block

language	xml
title	Example for Dutch spoken audio book:

<Language>
 <LanguageRole>01</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>
<Language>
 <LanguageRole>08</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>

Code Block

language	xml
title	Example for Dutch spoken audiobook, translated from Swedish

<Language>
 <LanguageRole>01</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>
<Language>
 <LanguageRole>02</LanguageRole>
 <LanguageCode>swe</LanguageCode>
</Language>
<Language>
 <LanguageRole>08</LanguageRole>
 <LanguageCode>dut</LanguageCode>
</Language>

Related products (ISBN) and related works (NSTC)

The ONIX feed can contain Related products. These products refer to the same work as the audiobook but with a different ProductForm. The supported ProductRelationCode is: 13 (= Epublication based on print product).

Code Block

language	xml
title	Example ONIX elements for Related ISBNs

<RelatedMaterial>
 <RelatedProduct>
  <ProductRelationCode>13</ProductRelationCode>
   <ProductIdentifier>
    <ProductIDType>03</ProductIDType>
    <IDValue>9789020211122</IDValue>
  </ProductIdentifier>
   <ProductIdentifier>
    <ProductIDType>15</ProductIDType>
    <IDValue>9789020211122</IDValue>
  </ProductIdentifier>
 </RelatedProduct>
</RelatedMaterial>

...

<Text textformat="02"><![CDATA[In Oorsprong van Dan Brown keert Robert Langdon weer terug om een van de grootste mysteries in zijn carrière op te lossen.

Robert Langdon, hoogleraar kunstgeschiedenis en symboliek, is te gast in het hypermoderne Guggenheim-museum in Bilbao, voor een belangrijke onthulling die de wetenschap voor altijd zal veranderen. De gastheer van de avond is Edmond Kirsch, een veertigjarige miljardair en futuroloog wiens oogverblindende hightech uitvindingen en gewaagde uitspraken hem wereldberoemd hebben gemaakt. Maar de zorgvuldig georkestreerde avond barst plotseling uit in chaos, waardoor Kirsch’ waardevolle ontdekking voorgoed dreigt te verdwijnen.
Samen met de elegante museumdirecteur Ambra Vidal vlucht Langdon naar Barcelona, waar ze een spoor volgen dat ze uiteindelijk oog in oog zal brengen met Kirsch’ schokkende
ontdekking…]]></Text>
</TextContent>

Image assets

In <SupportingResource>, the ONIX contains 2 references to image assets for the audiobook cover, using <FeatureNote> large and thumb. The images itself are supplied as jpg files.

The large cover image has a minimum resolution of 1024 x 1024 px (jpg, RGB), but sometimes higher resolutions (up to 3000 x 3000) are available. The size of the thumb cover image asset is always 512 x 512 px (jpg, RGB). It is the responsibility of the web shop to resize the cover images.

All images are served from the endpoint https://assets.luisterhuis.nl/. They must be downloaded and cached by the web shop. Hotlinking to the assets server is not supported.

Code Block

language	xml
title	The ONIX contains a reference to the NSTC as follows

Example for the lager image asset

<SupportingResource>
 <ResourceContentType>03</ResourceContentType>
 <ContentAudience>00</ContentAudience>
 <ResourceMode>03</ResourceMode>
 <ResourceVersion>
  <ResourceForm>02</ResourceForm>
  <ResourceVersionFeature>
   <IDTypeName>NSTC<<ResourceVersionFeatureType>01</IDTypeName>ResourceVersionFeatureType>
    <IDValue>100020228<<FeatureValue>D502</IDValue>FeatureValue>
  </WorkIdentifier>ResourceVersionFeature>
  <ResourceVersionFeature>
   <<ResourceVersionFeatureType>02</RelatedWork>
</RelatedMaterial>

Abridged / unabridged

The ONIX contains the <EditionType> element which refers to either abridged (content has been shortened in relation to the original book) or unabridged content.

There are 2 possible values for <EditionType> supported:

ABR Abridged
UBR Unabridged

Duration and size values

The ONIX contains duration and size values of the audiobook files.

Code Block

language	xml
title	Duration and size values

<Extent>
 <ExtentType>09</ExtentType>
 <ExtentValue>21287</ExtentValue>
 <ExtentUnit>06</ExtentUnit>
</Extent>
<Extent>
 <ExtentType>09</ExtentType>
 <ExtentValue>0055447</ExtentValue>
 <ExtentUnit>16</ExtentUnit>
</Extent>
<Extent>
 <ExtentType>22</ExtentType>
 <ExtentValue>197</ExtentValue>
 <ExtentUnit>19</ExtentUnit>
</Extent>

These are the supported types and units:

ExtentType

09 Duration (running time)
22 File size

ExtentUnit

06 seconds (integer value)
16 Hours minutes seconds (HHHMMSS)
19 Mbytes (integer value)

Price fields and territorial restrictions

...

ResourceVersionFeatureType>
   <FeatureValue>3000</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>03</ResourceVersionFeatureType>
   <FeatureValue>3000</FeatureValue>
  <FeatureNote>large</FeatureNote>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>04</ResourceVersionFeatureType>
   <FeatureValue>bookcover_org.jpg</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>05</ResourceVersionFeatureType>
   <FeatureValue>0.3</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>07</ResourceVersionFeatureType>
   <FeatureValue>289348</FeatureValue>
  </ResourceVersionFeature>
  <ResourceLink datestamp="20200129T104331">https://assets.luisterhuis.nl/cover/c2e347e7-7f60-47c3-876d-1adb2005ba81</ResourceLink>
    <ContentDate>
    <ContentDateRole>01</ContentDateRole>
    <Date dateformat="00">20200903</Date>
    </ContentDate>
  </ResourceVersion>
</SupportingResource>

Sample audio file asset

In <SupportingResource>, the ONIX contains a reference to an audiobook sample file. It is allowed to use this sample file for promotional purposes. The sample file is supplied in mp3 format, 96 / 128 / 192 / 256 kbps, CBR/VBR, (joint) stereo. The audio length is usually 1 to 5 minutes. In most cases the sample is hand-picked by the studio. However, in some cases, the sample is auto generated.

All samples are served from the endpoint https://assets.luisterhuis.nl/. They must be downloaded and cached by the web shop. Hotlinking to the assets server is not supported.

Code Block

language	xml
title	Sample audio file asset

<SupportingResource>
 <ResourceContentType>15</ResourceContentType>
 <ContentAudience>00</ContentAudience>
 <ResourceMode>02</ResourceMode>
 <ResourceVersion>
  <ResourceForm>02</ResourceForm>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>01</ResourceVersionFeatureType>
   <FeatureValue>A103</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
    <ResourceVersionFeatureType>04</ResourceVersionFeatureType>
    <FeatureValue>sample.mp3</FeatureValue>
  </ResourceVersionFeature>
  <ResourceLink datestamp="20200903T110746">https://assets.luisterhuis.nl/sample/377dfd1e-731a-4047-8040-ee051231f2b1</ResourceLink>
  <ContentDate>
   <ContentDateRole>01</ContentDateRole>
   <Date dateformat="00">20200129</Date>
  </ContentDate>
 </ResourceVersion>
</SupportingResource>

Content Detail

The "ContentDetail" element is used in metadata to provide information about the content items in an audiobook, including any chapter or scene titles. This is important for organizing and categorizing the content as well as for helping listeners find the parts they are looking for.

The ContentDetail block consists of multiple ContentItem elements, with each element representing a part of the table of contents.
Each ContentItem element has a LevelSequenceNumber, which indicates the hierarchical position of the corresponding part in the table of contents (1.1, 1.2, 1.3, etc.).
Within the ContentItem element, there is the AVItem element, which contains an AVItemType with a value of "03".

Code Block

language	xml
title	Example

<Price>
 <PriceType>01</PriceType>
 <PriceAmount>9.17</PriceAmount>
 <CurrencyCode>EUR</CurrencyCode>
 <Territory>
  <RegionsIncluded>WORLD</RegionsIncluded>
  <CountriesExcluded>NL</CountriesExcluded>
  </Territory>
</Price>
<Price>
 <PriceType>02</PriceType>
 <PriceAmount>9.99</PriceAmount>
 <Tax>
  <TaxType>01</TaxType>
  <TaxRateCode>R</TaxRateCode>
  <TaxRatePercent>9.00</TaxRatePercent>
  <TaxableAmount>9.17</TaxableAmount>
  <TaxAmount>0.82</TaxAmount>
 </Tax>
 <CurrencyCode>EUR</CurrencyCode>
 <Territory>
  <CountriesIncluded>NL</CountriesIncluded>
 </Territory>
</Price>
<Price>
 <PriceType>05</PriceType>
 <PriceAmount>6.42</PriceAmount>
 <CurrencyCode>EUR</CurrencyCode>
</Price>

Special sale prices (temporary discounts) are supported with <PriceType> 11 and 12 using <PriceDate> <PriceDateRole> 14 and 15 to define the period.

ProductForm and PrimaryContentType

For digital audiobooks, the following <ProductForm> is used:

Code Block

language	xml
title	ProductForm

<ProductForm>AJ</ProductForm>
<ProductFormDetail>A103</ProductFormDetail>
<PrimaryContentType>01</ PrimaryContentType>

The following values for <PrimaryContentType> are supported:

01 Audio (audiobook)
02 Performance (audio drama, theatre, cabaret)
03 Music Recording
04 Other Audio (nature sounds, soundscapes)
13 Other Speech Content (lectures, interviews, discussions, audio tours)

Image assets

In <SupportingResource>, the ONIX contains 2 references to image assets for the audiobook cover, using <FeatureNote> large and thumb. The images itself are supplied as jpg files.

The large cover image has a minimum resolution of 1024 x 1024 px (jpg, RGB), but sometimes higher resolutions (up to 3000 x 3000) are available. The size of the thumb cover image asset is always 512 x 512 px (jpg, RGB). It is the responsibility of the web shop to resize the cover images.

...

ContentDetail

Example ContentDetail
<ContentDetail>
  <ContentItem>
    <LevelSequenceNumber>1.1</LevelSequenceNumber>
    <AVItem>
      <AVItemType>03</AVItemType>
    </AVItem>
    <TitleDetail>
      <TitleType>01</TitleType>
      <TitleElement>
        <TitleElementLevel>04</TitleElementLevel>
        <TitleText>Proloog</TitleText>
      </TitleElement>
    </TitleDetail>
  </ContentItem>
  <ContentItem>
    <LevelSequenceNumber>1.2</LevelSequenceNumber>
    <AVItem>
      <AVItemType>03</AVItemType>
    </AVItem>
    <TitleDetail>
      <TitleType>01</TitleType>
      <TitleElement>
        <TitleElementLevel>04</TitleElementLevel>
        <TitleText>Hoofdstuk 1</TitleText>
      </TitleElement>
    </TitleDetail>
  </ContentItem>
  <ContentItem>
    <LevelSequenceNumber>1.3</LevelSequenceNumber>
    <AVItem>
      <AVItemType>03</AVItemType>
    </AVItem>
    <TitleDetail>
      <TitleType>01</TitleType>
      <TitleElement>
        <TitleElementLevel>04</TitleElementLevel>
        <TitleText>Hoofdstuk 2</TitleText>
      </TitleElement>
    </TitleDetail>
  </ContentItem>
</ContentDetail>

Related products (ISBN) and related works (NSTC)

The ONIX feed can contain Related products. These products refer to the same work as the audiobook but with a different ProductForm. The supported ProductRelationCode is: 13 (= Epublication based on print product).

Code Block

language	xml
title	Example for the lager image asset

ONIX elements for Related ISBNs

<RelatedMaterial>
 <RelatedProduct>
  <ProductRelationCode>13</ProductRelationCode>
   <ProductIdentifier>
    <ProductIDType>03</ProductIDType>
    <ResourceVersionFeatureType>01<<IDValue>9789020211122</ResourceVersionFeatureType>IDValue>
   <FeatureValue>D502<</FeatureValue>ProductIdentifier>
  </ResourceVersionFeature>  <ProductIdentifier>
<ResourceVersionFeature>    <ResourceVersionFeatureType>02<<ProductIDType>15</ResourceVersionFeatureType>ProductIDType>
    <FeatureValue>3000<<IDValue>9789020211122</FeatureValue>IDValue>
  </ResourceVersionFeature>ProductIdentifier>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>03</ResourceVersionFeatureType>
   <FeatureValue>3000</FeatureValue>
  <FeatureNote>large</FeatureNote>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>04</ResourceVersionFeatureType>
   <FeatureValue>bookcover_org.jpg</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>05</ResourceVersionFeatureType>
   <FeatureValue>0.3</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>07</ResourceVersionFeatureType>
   <FeatureValue>289348</FeatureValue>
  </ResourceVersionFeature>
  <ResourceLink datestamp="20200129T104331">https://assets.luisterhuis.nl/cover/c2e347e7-7f60-47c3-876d-1adb2005ba81</ResourceLink>
    <ContentDate>
    <ContentDateRole>01</ContentDateRole>
    <Date dateformat="00">20200903</Date>
    </ContentDate>
  </ResourceVersion>
</SupportingResource>

Sample audio file asset

In <SupportingResource>, the ONIX contains a reference to an audiobook sample file. It is allowed to use this sample file for promotional purposes. The sample file is supplied in mp3 format, 96 / 128 / 192 / 256 kbps, CBR/VBR, (joint) stereo. The audio length is usually 1 to 5 minutes. In most cases the sample is hand-picked by the studio. However, in some cases, the sample is auto generated.

...

</RelatedProduct>
</RelatedMaterial>

In addtion, CB assigns a unique work identifier called NSTC (Netherlaends Standard Text Code) to every work published in the Netherlands and Flanders. All product forms of a specific book (hardback, paperback, ebook, audiobook) have the same NSTC, which allows a web shop to group the different product forms of the same book. This value is less relevant for web shops that only offer audiobooks.

Code Block

language	xml
title	The ONIX contains a reference to the NSTC as follows

<RelatedMaterial>
 <RelatedWork>
  <WorkRelationCode>01</WorkRelationCode>
   <WorkIdentifier>
    <WorkIDType>01</WorkIDType>
    <IDTypeName>NSTC</IDTypeName>
    <IDValue>100020228</IDValue>
  </WorkIdentifier>
 </RelatedWork>
</RelatedMaterial>

Product availability

The value of the element <ProductAvailability> defines whether or not an audiobook product is allowed for sale / use or not. The ONIX contains a reference to the <ProductAvailability> as follows:

Code Block

language	xml
title	Product availability

<ProductSupply>
 <SupplyDetail>
  <ProductAvailability>20</ProductAvailability>
 </SupplyDetail>
</ProductSupply>

There are 3 possible values for <ProductAvailability>:

10 Announced (this includes a future SupplyDate)
20 Available
40 Withdrawn

It is the responsibility of the web shop client to comply with this standard, parse the <ProductAvailability> field, and show or take down the title when necessary.

Note
The audiobook may be enabled for sale only when <ProductAvailability> is 20 As soon as the <ProductAvailability> value changes to 40, the title needs to be disabled for sale in the web shop.

Behaviour of Announcements:

For audiobooks where the CB Online life cycle is set to ‘Aangekondigd’ (Announced), the ONIX element <ProductAvailability> will contain 10 and <PublishingStatus> will contain 02.
The expected delivery date of the complete audiobook (Expected availability date) is passed through <SupplyDate> and the <SupplyDateRole> with the value 08.
The formal publication date is specified in <PublishingDate> with a <PublishingDateRole> 01.
As soon as the life cycle in CB Online is set to 'Verschenen’ (Available), the element <ProductAvailability> will contain 20 and <PublishingStatus> will contain 04. <SupplyDate> with a <SupplyDateRole> 08 will then contain the delivery date of the complete audiobook (Expected availability date).

<SupportingResource> <ResourceContentType>15</ResourceContentType> <ContentAudience>00</ContentAudience> <ResourceMode>02</ResourceMode> <ResourceVersion> <ResourceForm>02</ResourceForm> <ResourceVersionFeature> <ResourceVersionFeatureType>01</ResourceVersionFeatureType> <FeatureValue>A103</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>04</ResourceVersionFeatureType> <FeatureValue>sample.mp3</FeatureValue> </ResourceVersionFeature> <ResourceLink datestamp="20200903T110746">https://assets.luisterhuis.nl/sample/377dfd1e-731a-4047-8040-ee051231f2b1</ResourceLink> <ContentDate> <ContentDateRole>01</ContentDateRole>

Code Block

language	xml
title	Sample audio file asset

Example ONIX elements for an announcement

<ProductSupply>
<SupplyDetail>
  <ProductAvailability>10</ProductAvailability>
  <SupplyDate>
   <SupplyDateRole>08</SupplyDateRole>
   <Date dateformat="00">20200129<>20221005</Date>
  </ContentDate>
/SupplyDate>
</SupplyDetail>
</ProductSupply>

<PublishingDetail>
<PublishingStatus>02</PublishingStatus>
<PublishingDate>
  <PublishingDateRole>01</PublishingDateRole>
  <Date dateformat="00">20221103</Date>
</ResourceVersion>PublishingDate>
</SupportingResource>PublishingDetail>

Product availability

The value of the element <ProductAvailability> defines whether or not an audiobook product is allowed for sale / use or not. The ONIX contains a reference to the <ProductAvailability> as follows:

Code Block

language	xml
title	Product availability

<ProductSupply>
 <SupplyDetail>
  <ProductAvailability>20</ProductAvailability>
 </SupplyDetail>
</ProductSupply>

There are 3 possible values for <ProductAvailability>:

10 Announced (this includes a future SupplyDate)
20 Available
40 Withdrawn

It is the responsibility of the web shop client to comply with this standard, parse the <ProductAvailability> field, and show or take down the title when necessary.

Note
The audiobook may be enabled for sale only when <ProductAvailability> is 20 As soon as the <ProductAvailability> value changes to 40, the title needs to be disabled for sale in the web shop.

Behaviour of Announcements:

...

Comments:

The publication date in the ONIX (<PublishingDate> with <PublishingDateRole> 01) may differ from the actual publication date, because of the following: if Bureau ISBN has not yet carried out the editorial check, the publisher can modify the publication date and updates will be specified in the ONIX for resellers. After Bureau ISBN has carried out the editorial check, the publication date is fixed. If in doubt, contact the publisher.
Announced audiobooks will not always have an audio sample, cover image, and/or sales price. The description and subject classification may also still be incomplete. As soon as the title has been published (<ProductAvailability> 20) there is always an audio fragment and cover image available, and the metadata has been checked and complete.
Orders for announced audiobooks will not be processed. These orders give an error. The web shop must therefore make its own provision for the possible registration of pre-orders. Orders will only be processed for audiobooks with a <ProductAvailability> 20.

Price fields and territorial restrictions

Luisterhuis provides at least a single RRP (recommended retail price) in the ONIX. The ONIX contains the correct RRP and special sale price (temporary discounted prices, with start and end date) as supplied by the publisher for this specific web shop. There are no ‘fixed book prices’, so it might be possible that the prices will differ between different web shops. Please note: the current (reduced) VAT percentage for digital audiobooks in The Netherlands is 9% and in Flanders is 6%.

Special sale prices (temporary discounts) are supported with <PriceType> 11 and 12 using <PriceDate> <PriceDateRole> 14 and 15 to define the period.

Code Block

language	xml
title	Example ONIX elements for an announcement

<ProductSupply><Price>
<SupplyDetail>   <ProductAvailability>10<<PriceType>01</ProductAvailability>PriceType>
  <SupplyDate>
   <SupplyDateRole>08</SupplyDateRole>
   <Date dateformat="00">20221005</Date>
  </SupplyDate>
</SupplyDetail>
</ProductSupply>

<PublishingDetail>
<PublishingStatus>02</PublishingStatus>
<PublishingDate>
  <PublishingDateRole>01</PublishingDateRole>
  <Date dateformat="00">20221103</Date>
</PublishingDate>
</PublishingDetail>

Comments:

...

<PriceAmount>9.17</PriceAmount>
 <CurrencyCode>EUR</CurrencyCode>
 <Territory>
  <RegionsIncluded>WORLD</RegionsIncluded>
  <CountriesExcluded>NL</CountriesExcluded>
  </Territory>
</Price>
<Price>
 <PriceType>02</PriceType>
 <PriceAmount>9.99</PriceAmount>
 <Tax>
  <TaxType>01</TaxType>
  <TaxRateCode>R</TaxRateCode>
  <TaxRatePercent>9.00</TaxRatePercent>
  <TaxableAmount>9.17</TaxableAmount>
  <TaxAmount>0.82</TaxAmount>
 </Tax>
 <CurrencyCode>EUR</CurrencyCode>
 <Territory>
  <CountriesIncluded>NL</CountriesIncluded>
 </Territory>
</Price>
<Price>
 <PriceType>05</PriceType>
 <PriceAmount>6.42</PriceAmount>
 <CurrencyCode>EUR</CurrencyCode>
</Price>

API for order placement

When to place an order

...

Versions Compared

Old Version 11

New Version Current

Key

ProductForm and PrimaryContentType

Title and collection

Short and long description/annotation

Contributor roles

PrefixToKey in contributor elements

Abridged / unabridged

Language codes

Duration and size values

Contributor roles

PrefixToKey in contributor elements

Subject metadata

Short and long description/annotation

Subject metadata

Language codes

Related products (ISBN) and related works (NSTC)

Image assets

Abridged / unabridged

Duration and size values

Price fields and territorial restrictions

Sample audio file asset

Content Detail

ProductForm and PrimaryContentType

Image assets

Related products (ISBN) and related works (NSTC)

Sample audio file asset

Product availability

Product availability

Price fields and territorial restrictions

API for order placement

When to place an order

Page Comparison

Versions Compared

Old Version 11

New Version Current

Key

ProductForm and PrimaryContentType

Title and collection

Short and long description/annotation

Contributor roles

PrefixToKey in contributor elements

Abridged / unabridged

Language codes

Duration and size values

Contributor roles

PrefixToKey in contributor elements

Subject metadata

Short and long description/annotation

Subject metadata

Language codes

Related products (ISBN) and related works (NSTC)

Image assets

Abridged / unabridged

Duration and size values

Price fields and territorial restrictions

Sample audio file asset

Content Detail

ProductForm and PrimaryContentType

Image assets

Related products (ISBN) and related works (NSTC)

Sample audio file asset

Product availability

Product availability

Price fields and territorial restrictions

API for order placement

When to place an order