Published by
Luisterhuis, a subsidiary of CB BV

More information
support@luisterhuis.nl

© 2010-2021 CB BV
This document contains confidential and proprietary information.
All rights reserved. No part of this publication may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm, without prior written consent of CB.

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

Introduction

About CB and Luisterhuis

CB is the main book distributor in the Netherlands and Flanders and the link between publisher, (online) bookseller and consumer. Over 1000 publishers and 1500 booksellers trust their logistics to CB for their physical books, POD publications, ebooks and audiobooks.

Dutch and Flemish publishers use CB as their digital distribution partner for ebooks (either PDF, EPUB2 or EPUB3) and audiobooks. With a suite of services available all in one portal, CB offers national and international e-tailers and platforms a one-stop-shop for access to the entire Dutch (language) market.

Publishers use the ‘CB Online’ web interface to offer their titles and data to any connected web shop retailer or platform. Publishers can offer their digital titles for sale, by subscription or for lending via a library. In addition to master files and metadata distribution, CB also offers invoicing services for the net pricing between publishers and e-tailers and provides insightful consolidated data reporting to the publishers using advanced analytics tools.

Luisterhuis, part of CB since 2020, handles digital fulfilment, offers extensive reports and provides master files and metadata to local and international web shops, library services, subscription platforms and other content platforms. For publishers, Luisterhuis is integrated into the CB Online web interface.

Luisterhuis offers different feeds and services to its B2B audiobook customers, like ONIX metadata web services, digital dropship delivery with download link fulfilment for web shops and (S)FTP based delivery of metadata and audiobook master files for audiobook platforms. Luisterhuis also ingests and processes all (monthly) sales and usage reports from audiobook retailers and platforms.

Audiobook web shop retailers and platforms are connected directly to the Luisterhuis system for both master file and metadata delivery and for reporting.

About this document

This documentation is intended for software developers and systems integrators who want to connect a web shop to the Luisterhuis distribution system to start selling digital audiobooks.
Luisterhuis operates as a RESTful web service and offers all tools necessary for an audiobook web shop:

It supplies a web shop with catalogue metadata, book-cover images and audio samples.
It accepts orders from a web shop and delivers the digital download links back to the web shop.
It handles the fulfilment of the digital audiobook download links for the end user.
It offers a web-based interface with a real time transaction overview, title repository and other info.
It uses the award winning BooXtream Audio social DRM protection system, which combines full MP3 compatibility with the assurance of minimized illegal use of the MP3 files.

Architecture

Luisterhuis as a digital distribution service

Luisterhuis operates as a distribution service between publishers of audiobooks and web shops.

It enables a web shop to sell audiobook downloads without actually storing and maintaining the audiobook files in the web shop. Instead, the web shop only has to implement a client interface to Luisterhuis to add audiobook metadata to its catalogue and to place orders. Everything else is handled by the Luisterhuis system, including the delivery of the protected MP3 files to the end user.

A simplified overview of the architecture:

A simplified overview of the architecture e

Delivering audiobooks to the end user

Luisterhuis stores all audio master files and all metadata of the audiobooks on its own secure servers. Luisterhuis does not deliver the audio files to the web shop. Instead, Luisterhuis only delivers audiobook metadata, such as price data, author, narrator, description, images and sound samples to the web shop by means of an API. This allows the API client (the web shop) to create and maintain its own catalogue. When an end user orders an audiobook in the web shop, the transaction details are forwarded to the Luisterhuis API. Luisterhuis then returns a set of download links to the web shop, intended for the end user. It is up to the web shop to provide these download links to the end user (in a web dialogue, by mail and/or in an account). When a download link is activated by the end user, Luisterhuis delivers the audio files directly to the enduser.

There are special cases in which a Luisterhuis client (such as a web shop, subscription platform, library system) does need to obtain the audiobook master files, for instance when the client is a closed ecosystem with its own delivery and fulfilment methods, like an app-based subscription platform or library service. For this type of content delivery, Luisterhuis offers a platform interface with a configurable export module, which is not described in this documentation.

Please contact support@luisterhuis.nl and ask about the audiobook integration for platforms.

MP3 packaging and tagging

Although the MP3 file format for audio files is a world standard, the usage of MP3 for audiobooks introduces three complications that needs to be addressed:

separate tracks with individual chapters,
file size
tagging.

In short:

Almost every audiobook is divided into separate audio files (usually one MP3 file per chapter). This means that a complete audiobook will consist of a collection of files but downloading separate MP3 files is not user friendly.
Audiobooks can be very large (10+ hours in duration is not unusual). This means that the amount of MB's to download can be large. A 15-hour long audiobook can easily be 1,5 GB.
Every modern MP3 audio player (device or app) is able to show and use embedded MP3 ID3 tags. These tags are used by the library in the player to show and sort by Title, Author, chapter title and some other values. Without these tags, the playing sequence can be unpredictable so it’s essential that all MP3 files contain the correct ID3 tags.
Older (car)players tend to use and show the MP3 file names, so it is essential that the audiobook files are created with usable file names in order to select the correct tracks and play them in the correct order.

The Luisterhuis distribution system automatically takes care of all of this by creating uniquely tagged and named MP3 files and packaging these in a ZIP file for easy download.

ZIP packaging

The size of a digital audiobook can vary from 20 MB to more than 2 GB each, depending on the length of the recording. Unlike ebooks, where the content involves only one single EPUB file, a digital audiobook consists of several MP3 audio files, with up to several hundreds of MP3 files for one audiobook. However, manually downloading a lot of MP3 files for one audiobook, is very unfriendly for the end user.

Because of this, all MP3 files are packed together into one or more ZIP files. A Luisterhuis ZIP file has a maximum size of 250 MB. Small audiobooks are supplied in a single ZIP file. Larger audiobooks use more ZIP files. This enables the end user to selectively download a large audiobook in parts, which is useful when download speeds are low or using a mobile device.

The ZIP files are build using the following naming convention:

identifier (zipnumber-numberofzips).zip

The identifier is either the ISBN or the short title of the audiobook.

Examples

For instance, a single ZIP file:
9789123456789 (01-01).zip

or a set of multiple ZIP files:
9780176543218 (01-02).zip
9780176543218 (02-02).zip

Read chapter 7 for more details about the delivery of the download links to the web shop and the customer.

MP3 file naming

Every MP3 file within this ZIP is named using a standard naming convention. This convention contains 4 parts: author name, audiobook title, track number info and chapter title

generic structure is:

author - title (xxx-yyy) trackname.mp3

Example

like this:
Herman Philipse, Fik Meijer, Maarten van Rossem, Vincent Icke - Heeft wetenschap nut (001-031) Inleiding.mp3

In this example
Author name	Herman Philipse, Fik Meijer, Maarten van Rossem, Vincent Icke
Audiobook title	Heeft wetenschap nut
Track number info	current track number (001) - total number of tracks (031)
Chapter title	Inleiding.

MP3 tagging

In addition, the Luisterhuis distribution system automatically adds the correct ID3v1 and ID3v2 tags to every audio file. The following tags are created dynamically by the Luisterhuis distribution system.

title	Track title (extracted from filename), preceded by the track number with leading zero's
artist	Author (primary name, derived from Luisterhuis metadata database)
album	Audiobook title (derived from Luisterhuis metadata database)
year	Year of publication (derived from Luisterhuis metadata database)
genre id	“Boeken en spraak”, “Audiobook” or “Speech”
track	Track number
comment	Dynamically generated Social DRM text, containing the name the publisher, name and email address of the end user, the name of the web shop.

Album art

Every MP3 audio file contains a watermarked hires image of the audiobook cover. Most modern MP3 audio players (devices and apps) will show this image.

BooXtream Audio Social DRM

Luisterhuis uses BooXtream Audio Social DRM. This means that every MP3 file is created on the fly, with dynamic created information about Luisterhuis, the web shop and the customer. These ‘watermarked’ MP3 files and the enclosed (cover) images within the MP3 file header contain personalized information and other digital fingerprints, like a hidden transactional based code which is different for every web shop transaction, every user and every client (web shop).

An MP3-file with BooXtream Social DRM can be traced back to the individual customer and to the web shop where the customer has bought the audiobook, but the files are 100% compatible with every (hardware and software) MP3 player.

Luisterhuis as central hub for audiobook apps

In addition to the core features of the Luisterhuis distribution system, Luisterhuis also supports audiobook apps with a dedicated set of API’s.

The main use of the app API is to support apps that offer audiobook download and play functions for audiobooks sold by a web shop. The audio content is served directly from the Luisterhuis audiobook repository, bypassing the ZIP delivery format explained earlier. The app API documentation is available on request. Mail to support@luisterhuis.nl

Overview of the Luisterhuis API’s

Introduction

On a day-to-day basis, the API is used as follows: the web shop queries the Luisterhuis Catalogue API web service once a day to process the new and modified product information. The Luisterhuis product information is used to update the web shop catalogue.

The Catalogue API offers several functions to query the Luisterhuis web service for audiobook products, such as a list of all products and a list of changed or new products since a specific date. The Luisterhuis web service returns full ONIX 3 metadata.

When an end user places an order in the web shop, the web shop places the same order at Luisterhuis using the Order API.

After a successful order, the web shop retrieves the download link(s) using the downloadinfo API. The download link has to be stored in a user account and/or sent to the end user.

Endpoints and authentication

The default production endpoint for the Luisterhuis API is:

Endpont for the Luisterhuis API	url
Default for production	https://rest.luisterhuis.nl
For testing puposes	https://stub-rest.luisterhuis.nl
	This so-called stub API has the same functionality as the production API. All audiobooks can be ordered. There is one exception: only “free” audiobooks (audiobooks with price € 0) can be downloaded. To test the API, the catalogue does contain free titles. Download links to paid audiobooks will be returned in the API but cannot not be fulfilled (downloaded). The web shop will not be charged for the orders that are placed in the stub. The stub database is a recent copy of the production database, but it is not modified on a daily basis. Therefore, it contains almost the same products as the production database, but differences can occur. Using the stub API will also give you access to real time reports of all transactions and sales through stub-www.luisterhuis.nl/reseller. (See Chapter 8).

Authentiction

Authentication for the REST API is implemented through the Basic Authentication protocol. Every web shop is provided with a LoginName and an AuthenticationKey. The HTTPS protocol is used for communication with the REST interface.

Quick overview of the API’s

The Luisterhuis API offers several functions to connect to your web shop. Below is a quick overview: They will be described in more detail in the following chapters.

Catalogue retrieval (see chapter 4)	Action	/v3/inventory/
	Method	GET
	Action	/v3/product/isbn/[ISBN]
	Method	GET
Order handling (see chapter 6)	Action	/submitOrder
	Method	POST
	Action	/confirmOrder
	Method	POST
	Action	/orderDirect
	Method	POST
Download link retrieval (see chapter 7)	Action	/downloadinfo/[orderid]
Download link retrieval (see chapter 7)	Method	GET

ONIX metadata

The Luisterhuis catalogue of audiobook products contains all metadata of the audiobooks, like author, publisher, prices et cetera. The data is supplied in XML following the international ONIX 3.0 guidelines.

ONIX for Books is a worldwide XML standard to describe book information. It enables connecting the servers of publishers, distributors and retailers, without any conversion or manual data entry of the book data. Information about the ONIX standard is available online on www.editeur.org

It is important to know that to process the Luisterhuis XML files, you will have to 'know' how ONIX works. We can recommend downloading the documentation here: http://www.editeur.org/93/Release- 3.0-Downloads/

Chapter 5 contains information about the specific ONIX elements for audiobooks.

The basic steps to sell audiobooks using Luisterhuis API’s

It all starts with the initial retrieval of the product catalogue from Luisterhuis to incorporate the metadata in your own system. After the Luisterhuis audiobook products are available in your system, you can sell them to your customers. You will also have to check regularly if there are new or changed products. (New products and updated metadata are added on a daily basis; sometimes the price or the description of an existing product can change). The functions for catalogue retrieval are described in Chapter 4.

When an audiobook is being sold from your system, it is common practice to first check if the product is still available at Luisterhuis. So, before you accept payment from your customer, check the availability. There is an API call for that. (In fact: there are two ways of checking: you can simply check, or you can combine the checking with the placement of an order). The reason is not that the product can be out of stock, but the product can be withdrawn from the catalogue due to commercial or legal reasons. The functions for order placement are described in Chapter 6.

After you have received a confirmation that the product is still available, you can proceed to the checkout procedure in your own shop and accept payment from your customer.

When your shop places an order at Luisterhuis, you will have to supply Luisterhuis with some details of the order, like the product(s) to order, the customer name and/or their e-mail address and your internal order number. After Luisterhuis accepts your order, it will supply you with a Luisterhuis order id.

Using this Luisterhuis order id, your shop can request the download link. This download link can be stored in a private area on your site, available only for your end user. And/or you can send the link by e-mail to your end user. Using this link, the end user can download the ZIP files containing the audiobooks. The functions for handling the download links are described in Chapter 7.

Accounting and reporting

Luisterhuis handles all end user orders and fulfils the download links. Therefore Luisterhuis ‘knows’ about every end user transaction. Luisterhuis aggregates this data for the various publishers and uses this data for invoicing and pay-out purposes.

Depending on the agreement the web shop has with CB, they might receive a monthly or quarterly receipt with a detailed description of all audiobooks retrieved, played and/or sold.

A representative of the web shop (usually a member of the support desk) also has access to a real time report of all transactions and sales reports through a dashboard located at www.luisterhuis.nl/reseller or stub-www.luisterhuis.nl/reseller (testing purposes).

This dashboard offers an overview of all available titles, all basic metadata and all transactions. The dashboard can also be used to reset already used (or expired) download links. The dashboard is described in detail in Chapter 8: Reseller dashboard for web shops.

API for catalogue and metadata

Summary of functions

Luisterhuis uses a RESTful web service to provide all audiobook metadata to a web shop.

The interface offers the following API functions:

Catalogue metadata in ONIX 3 format
Single product metadata in ONIX 3 format

It is best practice to call the API once a day every 24 hours (for instance every night between 02:00 and 06:00).

Catalogue metadata in ONIX 3 format

To retrieve all metadata of all available audiobooks available for the web shop you can use the inventory API call. The inventory call supports the retrieval of ONIX metadata of a full catalogue (inventory) or only the updates over a certain period (‘what’s new since yesterday’).

Action

/v3/inventory/

Method

GET

Parameters

offset&limit

?offset=[offset]&limit=[limit]

Offset defines the number of products to be skipped. Default is 0.
Limit defines the number of products in the ONIX. Default is 200, max is 500.

modifiedfrom

?modifiedfrom=[date]

Modifiedfrom filters on new and modified products from specified date and
time. Format date YYYYMMDDHHIISS, YYYY = year, MM = month, DD = day,
HH = hour, II = minute, SS = second

Timezone: CET/CEST (= UTC+2)

Example:

To retrieve the first 100 ONIX metadata records from all products, use:

https://rest.luisterhuis.nl/v3/inventory/?offset=0&limit=100

Click here to expand for ONIX message with 1 complete product metadata

<?xml version="1.0" encoding="UTF-8"?>
<ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" release="3.0">
	<Header>
		<Sender>
			<SenderIdentifier>
				<SenderIDType>10</SenderIDType>
				<IDValue>7237977</IDValue>
			</SenderIdentifier>
			<SenderName>Luisterhuis</SenderName>
			<ContactName>Content</ContactName>
			<EmailAddress>content@luisterhuis.nl</EmailAddress>
		</Sender>
		<MessageNumber>20210218162644</MessageNumber>
		<SentDateTime>20210218T1626</SentDateTime>
	</Header>
    <Product>
		<RecordReference>9789490938024</RecordReference>
		<NotificationType>03</NotificationType>
		<ProductIdentifier>
			<ProductIDType>01</ProductIDType>
			<IDValue>18</IDValue>
		</ProductIdentifier>
		<ProductIdentifier>
			<ProductIDType>03</ProductIDType>
			<IDValue>9789490938024</IDValue>
		</ProductIdentifier>
		<DescriptiveDetail>
			<ProductComposition>00</ProductComposition>
			<ProductForm>AJ</ProductForm>
			<ProductFormDetail>A103</ProductFormDetail>
			<PrimaryContentType>01</PrimaryContentType>
			<TitleDetail>
				<TitleType>01</TitleType>
				<TitleElement>
					<TitleElementLevel>01</TitleElementLevel>
					<TitleText>Alles wat je wilt weten over het heelal</TitleText>
					<Subtitle>Een Time2Learn luistercursus over het heelal</Subtitle>
				</TitleElement>
			</TitleDetail>
			<Contributor>
				<SequenceNumber>1</SequenceNumber>
				<ContributorRole>A01</ContributorRole>
				<NameIdentifier>
					<NameIDType>01</NameIDType>
					<IDTypeName>Luisterhuis AuthorID</IDTypeName>
					<IDValue>2860</IDValue>
				</NameIdentifier>
				<PersonName>Noortje Henrichs</PersonName>
				<NamesBeforeKey>Noortje</NamesBeforeKey>
				<KeyNames>Henrichs</KeyNames>
				<BiographicalNote textformat="02"><![CDATA[<br />]]></BiographicalNote>
			</Contributor>
			<Contributor>
				<SequenceNumber>2</SequenceNumber>
				<ContributorRole>A01</ContributorRole>
				<NameIdentifier>
					<NameIDType>01</NameIDType>
					<IDTypeName>Luisterhuis AuthorID</IDTypeName>
					<IDValue>2859</IDValue>
				</NameIdentifier>
				<PersonName>Adrienne Simons</PersonName>
				<NamesBeforeKey>Adrienne</NamesBeforeKey>
				<KeyNames>Simons</KeyNames>
				<BiographicalNote textformat="02"><![CDATA[<br />]]></BiographicalNote>
			</Contributor>
			<Contributor>
				<SequenceNumber>3</SequenceNumber>
				<ContributorRole>E07</ContributorRole>
				<PersonName>Martijn Warnas</PersonName>
				<NamesBeforeKey>Martijn</NamesBeforeKey>
				<KeyNames>Warnas</KeyNames>
			</Contributor>
			<Contributor>
				<SequenceNumber>4</SequenceNumber>
				<ContributorRole>E07</ContributorRole>
				<PersonName>Adrienne Simons</PersonName>
				<NamesBeforeKey>Adrienne</NamesBeforeKey>
				<KeyNames>Simons</KeyNames>
			</Contributor>
			<Contributor>
				<SequenceNumber>5</SequenceNumber>
				<ContributorRole>E07</ContributorRole>
				<PersonName>Matthé Smit</PersonName>
				<NamesBeforeKey>Matthé</NamesBeforeKey>
				<KeyNames>Smit</KeyNames>
			</Contributor>
			<EditionType>UBR</EditionType>
			<Language>
				<LanguageRole>01</LanguageRole>
				<LanguageCode>dut</LanguageCode>
			</Language>
			<Language>
				<LanguageRole>08</LanguageRole>
				<LanguageCode>dut</LanguageCode>
			</Language>
			<Extent>
				<ExtentType>09</ExtentType>
				<ExtentValue>3648</ExtentValue>
				<ExtentUnit>06</ExtentUnit>
			</Extent>
			<Extent>
				<ExtentType>09</ExtentType>
				<ExtentValue>0010048</ExtentValue>
				<ExtentUnit>16</ExtentUnit>
			</Extent>
			<Extent>
				<ExtentType>22</ExtentType>
				<ExtentValue>84</ExtentValue>
				<ExtentUnit>19</ExtentUnit>
			</Extent>
			<Subject>
				<MainSubject/>
				<SubjectSchemeIdentifier>10</SubjectSchemeIdentifier>
				<SubjectCode>SCI004000</SubjectCode>
			</Subject>
			<Subject>
				<MainSubject/>
				<SubjectSchemeIdentifier>32</SubjectSchemeIdentifier>
				<SubjectCode>400</SubjectCode>
			</Subject>
			<Subject>
				<SubjectSchemeIdentifier>32</SubjectSchemeIdentifier>
				<SubjectCode>910</SubjectCode>
			</Subject>
		</DescriptiveDetail>
		<CollateralDetail>
			<TextContent>
				<TextType>02</TextType>
				<ContentAudience>00</ContentAudience>
				<Text><![CDATA[Wat is een zwart-gat? Hoe lang heeft de aarde nog? Hoe is het universum ontstaan? Time2Learn legt het allemaal uit in duidelijke taal. Een complete cursus in één uur.]]></Text>
				<ContentDate>
					<ContentDateRole>01</ContentDateRole>
					<Date dateformat="00">20061115</Date>
				</ContentDate>
			</TextContent>
			<TextContent>
				<TextType>03</TextType>
				<ContentAudience>00</ContentAudience>
				<Text textformat="02"><![CDATA[Hebben sterrenstelsels en planeten altijd je fantasie geprikkeld? En ben je altijd geïnteresseerd geweest in alles wat buiten onze dampkring te vinden is? Dan is deze cursus een must!<br />
<br />In deze Time2Learn kun je genieten van de volgende modules: De aarde, de zon en de maan, de planeten, sterren en sterrenstelsels, Het einde van sterren, de oerknal en leven in de ruimte. We wensen je een leerzame tijd toe!<br>
<br>
<b>Inhoud</b><br>
Wil jij weten wat het universum jou te bieden heeft! Deze cursus vertelt je alles wat je moet weten!<br> 
- Wat is de Big-Crunch theorie?<br>
- Hoe snel draait onze aarde?<br>
- Wie speelde er golf op de maan?<br>
- Wat is een zwart-gat?<br>
- Hoelang heeft onze aarde nog?<br>
En nog veel meer dan dat!<br />]]></Text>
			</TextContent>
			<SupportingResource>
				<ResourceContentType>03</ResourceContentType>
				<ContentAudience>00</ContentAudience>
				<ResourceMode>03</ResourceMode>
				<ResourceVersion>
					<ResourceForm>02</ResourceForm>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>01</ResourceVersionFeatureType>
						<FeatureValue>D502</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>02</ResourceVersionFeatureType>
						<FeatureValue>1024</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>03</ResourceVersionFeatureType>
						<FeatureValue>1024</FeatureValue>
						<FeatureNote>large</FeatureNote>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>04</ResourceVersionFeatureType>
						<FeatureValue>bookcover_master.jpg</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>05</ResourceVersionFeatureType>
						<FeatureValue>0.4</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>07</ResourceVersionFeatureType>
						<FeatureValue>417099</FeatureValue>
					</ResourceVersionFeature>
					<ResourceLink datestamp="20200403T140451">https://assets.luisterhuis.nl/cover/875e5c7f-43b4-4978-ae23-6672cfa9e8cf</ResourceLink>
					<ContentDate>
						<ContentDateRole>01</ContentDateRole>
						<Date dateformat="00">20200128</Date>
					</ContentDate>
				</ResourceVersion>
				<ResourceVersion>
					<ResourceForm>02</ResourceForm>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>01</ResourceVersionFeatureType>
						<FeatureValue>D502</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>02</ResourceVersionFeatureType>
						<FeatureValue>512</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>03</ResourceVersionFeatureType>
						<FeatureValue>512</FeatureValue>
						<FeatureNote>thumb</FeatureNote>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>04</ResourceVersionFeatureType>
						<FeatureValue>bookcover_square.jpg</FeatureValue>
					</ResourceVersionFeature>
					<ResourceVersionFeature>
						<ResourceVersionFeatureType>07</ResourceVersionFeatureType>
						<FeatureValue>49127</FeatureValue>
					</ResourceVersionFeature>
					<ResourceLink datestamp="20200403T140451">https://assets.luisterhuis.nl/cover/98cfe6ee-3462-45ab-b7cf-5079da571c2d</ResourceLink>
					<ContentDate>
						<ContentDateRole>01</ContentDateRole>
						<Date dateformat="00">20200128</Date>
					</ContentDate>
				</ResourceVersion>
			</SupportingResource>
			<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="20200403T140455">https://assets.luisterhuis.nl/sample/01019cc1-b2b5-4b5b-80d7-e51e892cee59,1</ResourceLink>
					<ContentDate>
						<ContentDateRole>01</ContentDateRole>
						<Date dateformat="00">20200128</Date>
					</ContentDate>
				</ResourceVersion>
			</SupportingResource>
		</CollateralDetail>
		<PublishingDetail>
			<Imprint>
				<ImprintName>Time2Learn</ImprintName>
			</Imprint>
			<Publisher>
				<PublishingRole>01</PublishingRole>
				<PublisherIdentifier>
					<PublisherIDType>10</PublisherIDType>
					<IDValue>6780849</IDValue>
				</PublisherIdentifier>
				<PublisherName>Time2Learn</PublisherName>
				<Website>
					<WebsiteRole>18</WebsiteRole>
					<WebsiteDescription>Website uitgeverij</WebsiteDescription>
					<WebsiteLink>http://www.time2learn.nl</WebsiteLink>
				</Website>
			</Publisher>
			<PublishingStatus>04</PublishingStatus>
			<PublishingDate>
				<PublishingDateRole>01</PublishingDateRole>
				<Date dateformat="00">20061115</Date>
			</PublishingDate>
			<SalesRights>
				<SalesRightsType>01</SalesRightsType>
				<Territory>
					<RegionsIncluded>WORLD</RegionsIncluded>
				</Territory>
			</SalesRights>
		</PublishingDetail>
		<RelatedMaterial>
			<RelatedWork>
				<WorkRelationCode>01</WorkRelationCode>
				<WorkIdentifier>
					<WorkIDType>01</WorkIDType>
					<IDTypeName>NSTC</IDTypeName>
					<IDValue>500437832</IDValue>
				</WorkIdentifier>
			</RelatedWork>
		</RelatedMaterial>
		<ProductSupply>
			<Market>
				<Territory>
					<RegionsIncluded>WORLD</RegionsIncluded>
				</Territory>
			</Market>
			<SupplyDetail>
				<Supplier>
					<SupplierRole>00</SupplierRole>
					<SupplierName>Luisterhuis</SupplierName>
				</Supplier>
				<ProductAvailability>20</ProductAvailability>
				<Price>
					<PriceType>01</PriceType>
					<PriceAmount>7.33</PriceAmount>
					<CurrencyCode>EUR</CurrencyCode>
					<Territory>
						<RegionsIncluded>WORLD</RegionsIncluded>
						<CountriesExcluded>NL</CountriesExcluded>
					</Territory>
				</Price>
				<Price>
					<PriceType>02</PriceType>
					<PriceAmount>7.99</PriceAmount>
					<Tax>
						<TaxType>01</TaxType>
						<TaxRateCode>R</TaxRateCode>
						<TaxRatePercent>9.00</TaxRatePercent>
						<TaxableAmount>7.33</TaxableAmount>
						<TaxAmount>0.66</TaxAmount>
					</Tax>
					<CurrencyCode>EUR</CurrencyCode>
					<Territory>
						<CountriesIncluded>NL</CountriesIncluded>
					</Territory>
				</Price>
				<Price>
					<PriceType>05</PriceType>
					<PriceAmount>5.13</PriceAmount>
					<CurrencyCode>EUR</CurrencyCode>
				</Price>
			</SupplyDetail>
		</ProductSupply>
	</Product>
</ONIXMessage>

(This is a partial ONIX message with 1 complete Product record. See Chapter 5 for more information about ONIX).

Due to the size of the resulting metadata file, it’s not possible to retrieve all metadata for all titles in a single call. The limit for a single call is 500 titles. Therefore, it is necessary to retrieve the metadata in multiple calls using the offset&limit parameters, and to collect all result sets on your server. The modifiedfrom parameter is used to select a subset of all new or modified products since a specific date.

Usually, all these parameters are combined. The following example shows how the first, second and subsequent 500 ONIX metadata records from all new and modified products, since June 24, 2020 at 02.00.00, can be retrieved:

/v3/inventory/?offset=0&limit=500&modifiedfrom=20200624020000

/v3/inventory/?offset=500&limit=500&modifiedfrom=20200624020000

/v3/inventory/?offset=1000&limit=500&modifiedfrom=20200624020000

and so on, until no Product elements are returned. Such an ‘empty’ result set looks like this:

Click here to expand for example 'empty' result set

<?xml version="1.0" encoding="UTF-8"?>
<ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" release="3.0">
  <Header>
    <Sender>
      <SenderIdentifier>
        <SenderIDType>10</SenderIDType>
        <IDValue>7237977</IDValue>
      </SenderIdentifier>
      <SenderName>Luisterhuis</SenderName>
      <ContactName>Content</ContactName>
      <EmailAddress>content@luisterhuis.nl</EmailAddress>
    </Sender>
    <MessageNumber>20210218162644</MessageNumber>
    <SentDateTime>20210218T1626</SentDateTime>
  </Header>
</ONIXMessage>

Single product metadata in ONIX 3 format

If you know the ISBN of an audiobook and want to retrieve an uptodate metadata record, you could use the ‘product’ API call. All product metadata of a single audiobook can be retrieved like this:

Action		/v3/product/isbn/[ISBN] /* 13 character ISBN/EAN/UPC/GS1 product identifier*/
Method		GET
Example:		all metadata of an audiobook with ISBN 9789024577934, use this REST call: https://rest.luisterhuis.nl/v3/product/isbn/9789024577934/
Click here to expand example of complete Product record <?xml version="1.0" encoding="UTF-8"?> <ONIXMessage xmlns="http://ns.editeur.org/onix/3.0/reference" release="3.0"> <Header> <Sender> <SenderIdentifier> <SenderIDType>10</SenderIDType> <IDValue>7237977</IDValue> </SenderIdentifier> <SenderName>Luisterhuis</SenderName> <ContactName>Content</ContactName> <EmailAddress>content@luisterhuis.nl</EmailAddress> </Sender> <MessageNumber>20210218162742</MessageNumber> <SentDateTime>20210218T1627</SentDateTime> </Header> <Product> <RecordReference>9789024577934</RecordReference> <NotificationType>03</NotificationType> <ProductIdentifier> <ProductIDType>01</ProductIDType> <IDValue>4039</IDValue> </ProductIdentifier> <ProductIdentifier> <ProductIDType>03</ProductIDType> <IDValue>9789024577934</IDValue> </ProductIdentifier> <DescriptiveDetail> <ProductComposition>00</ProductComposition> <ProductForm>AJ</ProductForm> <ProductFormDetail>A103</ProductFormDetail> <PrimaryContentType>01</PrimaryContentType> <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> <Contributor> <SequenceNumber>1</SequenceNumber> <ContributorRole>A01</ContributorRole> <NameIdentifier> <NameIDType>01</NameIDType> <IDTypeName>Luisterhuis AuthorID</IDTypeName> <IDValue>1004</IDValue> </NameIdentifier> <PersonName>Dan Brown</PersonName> <NamesBeforeKey>Dan</NamesBeforeKey> <KeyNames>Brown</KeyNames> <BiographicalNote textformat="02"><![CDATA[<b>Dan Brown</b> (1964) is een van de succesvolste thrillerauteurs van het moment. Hij brak wereldwijd door met zijn thrillers <i>De Da Vinci Code</i>, <i>Het Bernini Mysterie</i>, <i>Het Verloren Symbool</i> en <i>Inferno</i>. September 2016, dertien jaar na het fenomenale, internationale succes van <i>De Da Vinci Code</i>, verschijnt een Young Adult versie voor 13+ van deze wereldwijde bestseller.<br /> <br /> Als zoon van een prijswinnend wiskundige en een moeder die religieuze muziek speelde, werd Dan Brown in zijn jeugd omringd door de tegengestelde ideeën van wetenschap en geloof. Deze tegenstellingen vormden de inspiratiebron voor <i>Het Bernini Mysterie</i>, het eerste boek met professor Robert Langdon in de hoofdrol. <br /> <br /> Tot hij besloot zich volledig op het schrijven te storten, doceerde Dan Brown Engels aan de Philips Exeter Acadamy. Samen met zijn vrouw Blythe, die kunsthistorica en schilderes is, gaat hij regelmatig op reis om research voor zijn boeken te doen.<br /> <br /> Op 3 oktober 2017 verscheen <i>Origin</i>, het nieuwe boek van Dan Brown.<br /> ]]></BiographicalNote> <Website> <WebsiteRole>06</WebsiteRole> <WebsiteDescription>Website van de auteur</WebsiteDescription> <WebsiteLink>http://www.danbrown.com</WebsiteLink> </Website> <Website> <WebsiteRole>42</WebsiteRole> <WebsiteDescription>Twitteradres van de auteur</WebsiteDescription> <WebsiteLink>http://www.twitter.com/AuthorDanBrown</WebsiteLink> </Website> <Website> <WebsiteRole>42</WebsiteRole> <WebsiteDescription>Facebookpagina van de auteur</WebsiteDescription> <WebsiteLink>http://www.facebook.com/DanBrown</WebsiteLink> </Website> </Contributor> <Contributor> <SequenceNumber>2</SequenceNumber> <ContributorRole>E07</ContributorRole> <PersonName>Casper Gimbrère</PersonName> <NamesBeforeKey>Casper</NamesBeforeKey> <KeyNames>Gimbrère</KeyNames> </Contributor> <EditionType>UBR</EditionType> <Language> <LanguageRole>01</LanguageRole> <LanguageCode>dut</LanguageCode> </Language> <Language> <LanguageRole>08</LanguageRole> <LanguageCode>dut</LanguageCode> </Language> <Extent> <ExtentType>09</ExtentType> <ExtentValue>62300</ExtentValue> <ExtentUnit>06</ExtentUnit> </Extent> <Extent> <ExtentType>09</ExtentType> <ExtentValue>0171820</ExtentValue> <ExtentUnit>16</ExtentUnit> </Extent> <Extent> <ExtentType>22</ExtentType> <ExtentValue>951</ExtentValue> <ExtentUnit>19</ExtentUnit> </Extent> <Subject> <MainSubject/> <SubjectSchemeIdentifier>10</SubjectSchemeIdentifier> <SubjectCode>FIC002000</SubjectCode> </Subject> <Subject> <MainSubject/> <SubjectSchemeIdentifier>10</SubjectSchemeIdentifier> <SubjectCode>FIC030000</SubjectCode> </Subject> <Subject> <MainSubject/> <SubjectSchemeIdentifier>10</SubjectSchemeIdentifier> <SubjectCode>FIC031000</SubjectCode> </Subject> <Subject> <SubjectSchemeIdentifier>20</SubjectSchemeIdentifier> <SubjectHeadingText>dan brown;geschiedenis;kunst;mysterie;religie;spanning;wetenschap</SubjectHeadingText> </Subject> <Subject> <MainSubject/> <SubjectSchemeIdentifier>32</SubjectSchemeIdentifier> <SubjectCode>332</SubjectCode> </Subject> <Subject> <SubjectSchemeIdentifier>32</SubjectSchemeIdentifier> <SubjectCode>305</SubjectCode> </Subject> <Subject> <MainSubject/> <SubjectSchemeIdentifier>93</SubjectSchemeIdentifier> <SubjectSchemeVersion>1.4</SubjectSchemeVersion> <SubjectCode>FHK</SubjectCode> </Subject> <Subject> <SubjectSchemeIdentifier>93</SubjectSchemeIdentifier> <SubjectSchemeVersion>1.4</SubjectSchemeVersion> <SubjectCode>FFD</SubjectCode> </Subject> <Subject> <SubjectSchemeIdentifier>93</SubjectSchemeIdentifier> <SubjectSchemeVersion>1.4</SubjectSchemeVersion> <SubjectCode>FJ</SubjectCode> </Subject> </DescriptiveDetail> <CollateralDetail> <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> <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> <SupportingResource> <ResourceContentType>04</ResourceContentType> <ContentAudience>00</ContentAudience> <ResourceMode>03</ResourceMode> <ResourceFeature> <ResourceFeatureType>06</ResourceFeatureType> <FeatureValue>1004</FeatureValue> </ResourceFeature> <ResourceVersion> <ResourceForm>02</ResourceForm> <ResourceVersionFeature> <ResourceVersionFeatureType>01</ResourceVersionFeatureType> <FeatureValue>D502</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>02</ResourceVersionFeatureType> <FeatureValue>140</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>03</ResourceVersionFeatureType> <FeatureValue>210</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>04</ResourceVersionFeatureType> <FeatureValue>Dan_Brown.jpg</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>07</ResourceVersionFeatureType> <FeatureValue>25382</FeatureValue> </ResourceVersionFeature> <ResourceLink>https://assets.luisterhuis.nl/author/Dan_Brown.jpg</ResourceLink> <ContentDate> <ContentDateRole>01</ContentDateRole> <Date dateformat="00">20200127</Date> </ContentDate> </ResourceVersion> </SupportingResource> <SupportingResource> <ResourceContentType>03</ResourceContentType> <ContentAudience>00</ContentAudience> <ResourceMode>03</ResourceMode> <ResourceVersion> <ResourceForm>02</ResourceForm> <ResourceVersionFeature> <ResourceVersionFeatureType>01</ResourceVersionFeatureType> <FeatureValue>D502</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>02</ResourceVersionFeatureType> <FeatureValue>1024</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>03</ResourceVersionFeatureType> <FeatureValue>673</FeatureValue> <FeatureNote>large</FeatureNote> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>04</ResourceVersionFeatureType> <FeatureValue>bookcover_master.jpg</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>05</ResourceVersionFeatureType> <FeatureValue>0.4</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>07</ResourceVersionFeatureType> <FeatureValue>460536</FeatureValue> </ResourceVersionFeature> <ResourceLink datestamp="20200129T104331">https://assets.luisterhuis.nl/cover/c2e347e7-7f60-47c3-876d-1adb2005ba81</ResourceLink> <ContentDate> <ContentDateRole>01</ContentDateRole> <Date dateformat="00">20200129</Date> </ContentDate> </ResourceVersion> <ResourceVersion> <ResourceForm>02</ResourceForm> <ResourceVersionFeature> <ResourceVersionFeatureType>01</ResourceVersionFeatureType> <FeatureValue>D502</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>02</ResourceVersionFeatureType> <FeatureValue>512</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>03</ResourceVersionFeatureType> <FeatureValue>512</FeatureValue> <FeatureNote>thumb</FeatureNote> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>04</ResourceVersionFeatureType> <FeatureValue>bookcover_square.jpg</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>05</ResourceVersionFeatureType> <FeatureValue>0.1</FeatureValue> </ResourceVersionFeature> <ResourceVersionFeature> <ResourceVersionFeatureType>07</ResourceVersionFeatureType> <FeatureValue>56704</FeatureValue> </ResourceVersionFeature> <ResourceLink datestamp="20200129T104331">https://assets.luisterhuis.nl/cover/4aaa36c3-b297-4686-b9ba-f8f8e736cd59</ResourceLink> <ContentDate> <ContentDateRole>01</ContentDateRole> <Date dateformat="00">20200129</Date> </ContentDate> </ResourceVersion> </SupportingResource> <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="20200825T150803">https://assets.luisterhuis.nl/sample/377dfd1e-731a-4047-8040-ee051231f2b1,1</ResourceLink> <ContentDate> <ContentDateRole>01</ContentDateRole> <Date dateformat="00">20200129</Date> </ContentDate> </ResourceVersion> </SupportingResource> </CollateralDetail> <PublishingDetail> <Imprint> <ImprintName>Uitgeverij Luitingh-Sijthoff</ImprintName> </Imprint> <Publisher> <PublishingRole>01</PublishingRole> <PublisherIdentifier> <PublisherIDType>10</PublisherIDType> <IDValue>7700068</IDValue> </PublisherIdentifier> <PublisherName>LS Amsterdam</PublisherName> <Website> <WebsiteRole>18</WebsiteRole> <WebsiteDescription>Website uitgeverij</WebsiteDescription> <WebsiteLink>http://www.lsamsterdam.nl</WebsiteLink> </Website> <Website> <WebsiteRole>43</WebsiteRole> <WebsiteDescription>Twitteradres van de uitgeverij</WebsiteDescription> <WebsiteLink>http://www.twitter.com/lsamsterdam</WebsiteLink> </Website> <Website> <WebsiteRole>43</WebsiteRole> <WebsiteDescription>Facebookpagina van de uitgeverij</WebsiteDescription> <WebsiteLink>http://www.facebook.com/lsamsterdam</WebsiteLink> </Website> </Publisher> <PublishingStatus>04</PublishingStatus> <PublishingDate> <PublishingDateRole>01</PublishingDateRole> <Date dateformat="00">20171003</Date> </PublishingDate> <SalesRights> <SalesRightsType>01</SalesRightsType> <Territory> <RegionsIncluded>WORLD</RegionsIncluded> </Territory> </SalesRights> </PublishingDetail> <RelatedMaterial> <RelatedWork> <WorkRelationCode>01</WorkRelationCode> <WorkIdentifier> <WorkIDType>01</WorkIDType> <IDTypeName>NSTC</IDTypeName> <IDValue>500099407</IDValue> </WorkIdentifier> </RelatedWork> <RelatedProduct> <ProductRelationCode>06</ProductRelationCode> <ProductRelationCode>13</ProductRelationCode> <ProductIdentifier> <ProductIDType>03</ProductIDType> <IDValue>9789024577941</IDValue> </ProductIdentifier> <ProductForm>AA</ProductForm> </RelatedProduct> <RelatedProduct> <ProductRelationCode>06</ProductRelationCode> <ProductIdentifier> <ProductIDType>03</ProductIDType> <IDValue>9789024576791</IDValue> </ProductIdentifier> <ProductForm>BC</ProductForm> </RelatedProduct> <RelatedProduct> <ProductRelationCode>06</ProductRelationCode> <ProductIdentifier> <ProductIDType>03</ProductIDType> <IDValue>9789024577927</IDValue> </ProductIdentifier> <ProductForm>BB</ProductForm> </RelatedProduct> <RelatedProduct> <ProductRelationCode>06</ProductRelationCode> <ProductIdentifier> <ProductIDType>03</ProductIDType> <IDValue>9789024576807</IDValue> </ProductIdentifier> <ProductForm>ED</ProductForm> </RelatedProduct> <RelatedProduct> <ProductRelationCode>06</ProductRelationCode> <ProductIdentifier> <ProductIDType>03</ProductIDType> <IDValue>9789049805708</IDValue> </ProductIdentifier> <ProductForm>BC</ProductForm> </RelatedProduct> </RelatedMaterial> <ProductSupply> <Market> <Territory> <RegionsIncluded>WORLD</RegionsIncluded> </Territory> </Market> <SupplyDetail> <Supplier> <SupplierRole>00</SupplierRole> <SupplierName>Luisterhuis</SupplierName> </Supplier> <ProductAvailability>20</ProductAvailability> <Price> <PriceType>01</PriceType> <PriceAmount>16.50</PriceAmount> <CurrencyCode>EUR</CurrencyCode> <Territory> <RegionsIncluded>WORLD</RegionsIncluded> <CountriesExcluded>NL</CountriesExcluded> </Territory> </Price> <Price> <PriceType>02</PriceType> <PriceAmount>17.99</PriceAmount> <Tax> <TaxType>01</TaxType> <TaxRateCode>R</TaxRateCode> <TaxRatePercent>9.00</TaxRatePercent> <TaxableAmount>16.50</TaxableAmount> <TaxAmount>1.49</TaxAmount> </Tax> <CurrencyCode>EUR</CurrencyCode> <Territory> <CountriesIncluded>NL</CountriesIncluded> </Territory> </Price> <Price> <PriceType>05</PriceType> <PriceAmount>11.55</PriceAmount> <CurrencyCode>EUR</CurrencyCode> </Price> </SupplyDetail> </ProductSupply> </Product> </ONIXMessage> See Chapter 5 for more information about ONIX.

ONIX metadata

Background

The Luisterhuis catalogue of audiobook products contains all metadata of the audiobooks, like author, publisher, prices et cetera. The data is supplied in XML following the ONIX 3.0 guidelines.

ONIX for Books is a worldwide XML standard to describe book information, to be able to connect the servers of publishers, distributors and retailers, without any conversion or manual data entry of the book data. Information about the ONIX standard is available online on www.editeur.org. We recommend downloading the most current documentation on http://www.editeur.org/93/Release-3.0-Downloads/

The current supported ONIX version by Luisterhuis is a subset of ONIX 3.0 revision 7 with ONIX Code Lists Issue 49. Please note: the ONIX metadata will always be supplied using full reference names.
In this chapter we’ll discuss the subset used by Luisterhuis. Test ONIX XML-files are available on request.

Web shop specific ONIX

Luisterhuis creates web shop specific ONIX metadata. The content is based on a combination of parameters of the underlying CB Online system. The ONIX is tailored and personalized to the specific web shop. For instance, catalogue selection, pricing and publication dates can differ from web shop to web shop based on agreements with publishers.

Local ONIX best practices

Since CB and Luisterhuis both have their roots in the Dutch language publishing market, the ONIX 3.0 subset used by Luisterhuis is highly compatible with the Dutch ONIX subset defined by CB. CB is Charter Member of EDItEUR and takes part in the Dutch language ONIX working group. CB maintains the ‘best practice’ for ONIX in the Dutch language area.

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:

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:

Title detail:

Title (Title is alway available. The elements are optional)
Sub title

Click here for an example without collection

			<TitleDetail>
				<TitleType>01</TitleType>
				<TitleElement>
					<TitleElementLevel>01</TitleElementLevel>
					<TitleText>Alles wat je wilt weten over het heelal</TitleText>
					<Subtitle>Een Time2Learn luistercursus over het heelal</Subtitle>
				</TitleElement>
			</TitleDetail>

Collection:

Series title
Series part number

Click here for an example with collection

			<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>

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:

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.

Example for Dutch spoken audio book:

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

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.

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	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	BISAC <Subject> <MainSubject/> <SubjectSchemeIdentifier>10</SubjectSchemeIdentifier> <SubjectCode>HIS010020</SubjectCode> </Subject>	Multiple BISAC values are supported. The main BISAC subject has the tag <MainSubject/>.
Thema	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	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:

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:

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>

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.

Example for the lager image asset

<SupportingResource>
 <ResourceContentType>03</ResourceContentType>
 <ContentAudience>00</ContentAudience>
 <ResourceMode>03</ResourceMode>
 <ResourceVersion>
  <ResourceForm>02</ResourceForm>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>01</ResourceVersionFeatureType>
   <FeatureValue>D502</FeatureValue>
  </ResourceVersionFeature>
  <ResourceVersionFeature>
   <ResourceVersionFeatureType>02</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.

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".

Example 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).

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>

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.

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:

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.

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).

Example ONIX elements for an announcement

<ProductSupply>
<SupplyDetail>
  <ProductAvailability>10</ProductAvailability>
  <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:

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.

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>

API for order placement

When to place an order

If the web shop sells an audiobook, it needs to place an order using the Luisterhuis API for order placement, which is described in this chapter.

Placing an order results in the creation of one or more download links pointing to ZIP files with MP3 audio files. The web shop needs to request these download links by using the downloadinfo API, which is described in chapter 7. Once the web shop has retrieved the download links, it can present them to the end user (eg. by email, on a web page, by storing them in a user account or by using a combination of these).

When a web shop places an order, it will be invoiced. This happens no matter if the download links have been activated or not. There is one exception: the order can be cancelled within 7 days after the transaction date. For more info, see Chapter 8.3 Sales.

The download links usually have a limited lifetime of 90 days. If a download link is expired, the expiration date can be reset manually using the Reseller dashboard for web shops, see Chapter 8.3 Sales.

The ordering modes: double or single call

Web shops can place an order in two ways: either through a submit/confirm combination (2 API calls) or by a direct order (a single API call).

Submit/confirm

With the ‘submit/confirm' combination the web shop uses submitOrder to check and reserve an order just before the customer pays for it. This mode is designed to be used within a shopping basket, to check if the ordered titles are available. If Luisterhuis responses with 200 OK, this ensures all the products are available. After the customer has paid for the order, the web shop uses confirmOrder to confirm the reserved order. If the order is not confirmed it is discarded by Luisterhuis.

Direct order

With 'direct order' the web shop uses directOrder after the customer has paid for it. A confirmation is not necessary, but the web shop doesn’t know beforehand if the order can be fulfilled. This might result in the (rare) situation that the title might not be available although the customer has paid for it.

Which mode to choose

The submit/confirm combination (described in chapters 6.4 and 6.5) is recommended, since this ensures that the customer will not pay for products that are (temporarily) unavailable. It also offers a mechanism to show the availability of a product while adding them to a shopping basket.
Direct order is easier to implement. However, if a web shop uses direct order (chapter 6.6), the web shop must have a provision in place to handle (temporarily) unavailable audiobooks and possible refunds.

Variables used in API

The following variables are used in the client order API (described in chapter 6.4 to 6.6):

ResellerOrderID	varchar(40)	This is the web shop’s internal order id (needs to be unique). It refers to one or more products, ordered by a single customer. It is visible in the Reseller dashboard for web shops (see Chapter 8).
CustomerEmailAddress	varchar(255)	Used to store the actual email address of the end user. The value is used for the BooXtream Audio Social DRM and is also visible in the Reseller dashboard for web shops (see Chapter 8). Although the use of this value can be helpful for several (support related) reasons, it is allowed to store different text content in this variable, like a random string. This might solve any doubts related to AVG / GDPR legislation.
CustomerID	varchar(255)	Used to store the internal ID of the end user. It uniquely identifies an end user (since an email address can change over time).
CustomerName	varchar(255)	Used to store the full name of the end user. It is used for the BooXtream Audio Social DRM and is also visible in the Reseller dashboard for web shops (see Chapter 8). Although the use of this value can be helpful for several (support related) reasons, it is allowed to store different text content in this variable, like a random string. This might solve any doubts related to AVG / GDPR legislation.
OrderID	int(11)	Refers to a unique order, containing one or more products, ordered by a single customer. The value is generated by Luisterhuis and is visible in the Reseller dashboard for web shops (see Chapter 8). It is used to retrieve the download links from the order.
OrderStatus	boolean	Indicates the status of the order. Value 0: the order is not yet confirmed and will be deleted after 30 days. Value 1: the order is confirmed. Product is available, download links can be requested. Web shop will be charged within 7 days.
SuppliersPrice	eurocents	The price that will be invoiced to the web shop when a product is sold. Can be 0 for free audiobooks.

Submit Order

To request the download links for one or more audiobooks, the web shop needs to submit an order using the submitOrder API.

The web shop usually activates this call when one or more audiobooks are sold or when or voucher code is redeemed in the web shop.

The submitOrder API call also can be used to check if the audiobook is available in the Luisterhuis repository. If it is, a HTTP status 200 OK is returned, and the order is registered (but not validated). If it isn't available, an error is returned. Only when a confirmOrder (see 6.4) is called, the (registered) order will be validated and processed. If no confirmOrder follows, the registered order will be discarded after 30 days.

Please note: Luisterhuis requires a CustomerID, a CustomerEmailAddress and a CustomerName for customer identification. The CustomerID is leading for all orders. The name can be considered as additional information. It is up to the web shop to register and manage customers with their respective customer-id's, email addresses, names and passwords.

REQUEST		The web shop submits an order to Luisterhuis by posting a RESTful XML message
Action		/submitOrder
Method		POST
Content-type		application/xml
Body:		<?xml version="1.0" encoding="UTF-8"?> <Order> <ResellerOrderID>ord#98765</ResellerOrderID> /* order id from web shop / <CustomerEmailAddress>enduser@domain.com</CustomerEmailAddress> / customer emailaddress / <CustomerName>Mrs. End User</CustomerName> / Full name required for social DRM / <CustomerID>756493764</CustomerID> / The web shop internal customer id / <Products> <Product> <EAN13>9789012345678</EAN13> / EAN13 (ISBN) audiobook / </Product> <Product> / more products in single message (optional / <EAN13>9789409876543</EAN13> / best practice: use 1 product per order */ </Product> ... </Products> </Order>
RESPONSE
HTTP Status 200 OK		200 OK <Message> <Request> <Order> <!— Copy of submitOrder --> </Order> </Request> <Response> <Code>200</Code> <Msg>OK</Msg> <Order> <OrderID></OrderID> <OrderStatus>0</OrderStatus> <Products> <Product> <EAN13>9789012345678</EAN13> <ProductID>123</ProductID> <SuppliersPrice>1879</SuppliersPrice> </Product> <Product> <EAN13>9789409876543</EAN13> <ProductID>345</ProductID> <SuppliersPrice>3092</SuppliersPrice> </Product> </Products> </Order> </Response> </Message>
HTTP Status 409 Conflict		409 Conflict <Message> <Request> <Order> <!— Repetition of Request Order --> </Order> </Request> <Response> <Code>100</Code> <Msg>Products Not Available</Msg> <Order> <Products> <Product> <EAN13>9789012345678</EAN13> <ProductID>123</ProductID> <SuppliersPrice>1879</SuppliersPrice> </Product> <Product> <EAN13>9789409876543</EAN13> <ProductID>345</ProductID> <SuppliersPrice>3092</SuppliersPrice> </Product> </Products> </Order> </Response> </Message>
HTTP Status 422 Unprocessable Entity		422 Unprocessable Entity <Message> <Request> <Order> <!— Repetition of Request Order --> </Order> </Request> <Response> <Code>1001</Code> <Msg>One Or More Mandatory Fields Are Empty</Msg> </Response> </Message>
HTTP Status 400 Bad Request		400 Bad Request <Message> <Request> <Order> <!— Repetition of Request Order --> </Order> </Request> <Response> <Code>400</Code> <Msg>Bad Request</Msg> </Response> </Message>

Best practice:
The web shop stores the OrderID and OrderStatus from Luisterhuis and links both values to its own internal order-id.

The price field refers to the supplier price for the ordered product. It is not the end user price; it is the discounted price to be invoiced to the web shop.

All orders with OrderStatus = 0 still need to be confirmed before becoming active (see 6.5). If OrderStatus remains 0 for 30 days, the order will be discarded by Luisterhuis.

Confirm Order

After a successful submitOrder (see 6.4), the web shop needs to confirm the order to request a set of download links of the audiobook.

REQUEST		The web shop confirms a previously submitted order to Luisterhuis by posting a RESTful XML message:
Action		/confirmOrder
Method		POST
Content-type		application/xml
Body:		Body <Order> <OrderID> /* internal order-id from Luisterhuis */ </Order>
RESPONSE
HTTP Status 200 OK		200 OK <Message> <Request> <!— Copy of confirmOrder --> </Request> <Response> <Code>200</Code> /* 200 = OK / <Msg>OK</Msg> <Order> <OrderID>123456789</OrderID> / internal order-id from Luisterhuis / <OrderStatus>1</OrderStatus> / orderstatus 1 = validated </Order> </Response> </Message>
		Luisterhuis now has registered a valid order for one or more audiobooks for a specific customer. The order will be billed after 7 days. The billing is independent of the actual download of the audiobook files. After confirmation, the download links can be requested. See chapter 7 to retrieve a download link for this order. The order can be canceled within 7 days. See Chapter 8.3 for more details.
HTTP Status 422 Unprocessable Entity		422 Unprocessable Entity <Message> <Request> <Order> <OrderID></OrderID> </Order> </Request> <Response> <Code>1000</Code> <Msg>Invalid OrderID</Msg> </Response> </Message>
HTTP Status 422 Unprocessable Entity		422 Unprocessable Entity <Message> <Request> <Order> <OrderID>123456789</OrderID> /* internal order-id from Luisterhuis */ </Order> </Request> <Response> <Code>1001</Code> <Msg>Invalid OrderID/ResellerID Combination</Msg> </Response> </Message>
HTTP Status 400 Bad Request		400 Bad Request <Message> <Request> <Order> <!— Copy of Order --> </Order> </Request> <Response> <Code>400</Code> <Msg>Bad Request</Msg> </Response> </Message>

Order Direct

With orderDirect the web shop places the order after the customer has paid for it. A confirmation call is not necessary, but the web shop doesn’t know beforehand if the order can be fulfilled. Products that have been withdrawn from Luisterhuis after the ONIX catalogue has been retrieved (so when the shop is unaware of this) can not be delivered and will result in an error. In that case the web shop should probably refund the order to the customer.

Luisterhuis now has registered a valid order for one or more audiobooks for a specific customer. The order will be billed after 7 days. The billing is independent of the actual download of the audiobook files. After confirmation, the download links can be requested. See chapter 7 to retrieve a download link for this order. The order can be canceled within 7 days. See Chapter 8.3 for more details.

REQUEST
Action		/orderDirect
Method		POST
Content-type		application/xml
Body:		Body <Order> <ResellerOrderID>ord#98765</ResellerOrderID> /* order id from web shop / <CustomerEmailAddress>enduser@domain.com</CustomerEmailAddress> / customer emailaddress / <CustomerName>Mrs. End User</CustomerName> / Full name required for social DRM / <CustomerID>756493764</CustomerID> / The web shop internal customer id / <Products> <Product> <EAN13>9789012345678</EAN13> / An EAN13 is required / </Product> <Product> <EAN13>9789012345645</EAN13> / Optionally, multiple EAN’s can be ordered per call/ </Product> / however, best practice is 1 product per order*/ </Products> </Order>
RESPONSE
HTTP Status 200 OK		200 OK <Message> <Request> <!— Copy of Request Order --> </Request> <Response> <Code>200</Code> /* 200 = OK / <Msg>OK</Msg> <Order> <OrderID>123456789</OrderID> / internal order-id from Luisterhuis */ <OrderStatus>0</OrderStatus> <Products> <Product> <EAN13>9789012345678</EAN13> <ProductID>123</ProductID> <SuppliersPrice>1879</SuppliersPrice> </Product> <Product> <EAN13>9789409876543</EAN13> <ProductID>345</ProductID> <SuppliersPrice>3092</SuppliersPrice> </Product> </Products> </Order> </Response> </Message>
HTTP Status 409 Conflict		409 Conflict <Message> <Request> <!— Repetition of Request Order --> </Order> </Request> <Response> <Code>1000</Code> <Msg>Products Not Available</Msg> <Products> <Product> <EAN13>9789012345678</EAN13> <ProductID>123</ProductID> <SuppliersPrice>1879</SuppliersPrice> </Product> <Product> <EAN13>9789409876543</EAN13> <ProductID>345</ProductID> <SuppliersPrice>3092</SuppliersPrice> </Product> </Products> </Response> </Message>
HTTP Status 422 Unprocessable Entity		422 Unprocessable Entity <Message> <Request> <Order> <!— Repetition of Request Order --> </Order> </Request> <Response> <Code>1001</Code> <Msg>One Or More Mandatory Fields Are Empty</Msg> </Response> </Message>
HTTP Status 400 Bad Request		400 Bad Request <Message> <Request> <Order> <!— Repetition of Request Order --> </Order> </Request> <Response> <Code>400</Code> <Msg>Bad Request</Msg> </Response> </Message>

API for download links

Introduction

Once a valid order has been registered (see Chapter 6), the web shop can retrieve the download links pointing to the audiobooks from Luisterhuis. This is done by using the downloadinfo API. If necessary, this API can be called multiple times. This doesn’t result in any extra billing.

In addition to the download links, the downloadinfo API also returns the ISBN and the actual file size of the files to be downloaded. This information can be used as extra information for the end user. For instance, it can be shown in the customer account and / or added to a confirmation email.

Please note that, depending on the total size of the audiobook, the mp3 files for a single product can be distributed over multiple ZIP-files. In other words: a single audiobook can consist of more than one download link. See below for more information about the ZIP files and download links.

Retrieve download links with the downloadinfo API

The web shop can request the download links by using the downloadinfo API, which requires a Luisterhuis OrderID. It is common practice to store the download links in a private account in the web shop, accessible only to the end user. It is also possible to send the links to the end user by email. Using these links, the end user can download the ZIP files containing the audiobooks.

REQUEST
Action		/downloadinfo/[orderid] /* OrderID is the Luisterhuis OrderID, as retrieved by confirmOrder or orderDirect */
Method		GET
Example		https://rest.luisterhuis.nl/downloadinfo/123456789
RESPONSE
HTTP Status 200 OK		200 OK <Message> <Request> <!— Copy of downloadinfo --> </Request> <Response> <Code>200</Code> /* 200 = OK / <Msg>OK</Msg> <Order> <OrderID>123456789</OrderID> / internal order-id from Luisterhuis / <OrderStatus>0</OrderStatus> <Products> <Product> <EAN13>9789403135717</EAN13> / ISBN of this audiobook / <ProductID>25055</ProductID> / Internal reference. Can be ignored* / <SuppliersPrice>0</SuppliersPrice> <Sets> <Set> <Number>01</Number> /* Set#1, every set max 256MB / <Filesize format="megabytes">213</Filesize> <DownloadLink>[link]</DownloadLink> / download link for ZIP with MP3/ </Set> <Set> <Number>02</Number> / set #2, if audiobook > 256MB/ <Filesize format="megabytes">169</Filesize> <DownloadLink>[link]</DownloadLink> / download link for second / </Set> / ZIP-file / ... / more sets are possible / </Sets> </Product> <Product> <EAN13>9789025881283</EAN13> <ProductID>25513</ProductID> <SuppliersPrice>2230</SuppliersPrice> <Sets> <Set> <Number>01</Number> <Filesize format="megabytes">157</Filesize> <DownloadLink>[link]</DownloadLink> </Set> </Sets> </Product> ... / more products are possible */ </Product> </Products> </Order> </Response> </Message>

The ZIP-files with MP3 audio

The response of the downloadinfo API contains one or a set of multiple URLs pointing to a ZIPfile.

Every zip file contains one or more MP3 files. Larger audiobooks are offered in multiple ZIP files, each 250 MB in size. Eg. an audiobook of 1.1 GB is offered as 5 ZIP files (4 x 250 MB and 1 x 100 MB), resulting in 5 download links.
The download link to a single ZIP file looks like this:

Download link single ZIP file

https://download.luisterhuis.nl/4950838014c88b09e07bad8.57098465/01/9789085301974 (01-01).zip

A typical set of download links to multiple ZIP files (all ZIP-files, except for the last one, having a size of 250 MB) looks like this:

Set of download links to multiple ZIP files

https://download.luisterhuis.nl/11759749014c8e31bc2ccd28.87142863/01/9789085301974 (01-02).zip
https://download.luisterhuis.nl/11759749014c8e31bc2ccd28.87142863/02/9789085301974 (02-02).zip

For more info about the actual content of the ZIP files see chapter 2.3

Download link lifetime and reset

The download links will have a limited lifetime of 365 days. Once activated, a download link can be used for another 90 days. This limited lifetime reduces misuse of the download links and prevents illegal downloads by sharing download links with other people.

When a customer activates a download link after 90 days, an error message is shown. This message contains information about the issue and who to contact at the web shop:

Let op: downloadlink niet meer actief. Uw download is gekocht op 2010-09-13 en is nu verlopen.

U kunt een luisterboek tot 2021-01-01 downloaden, of - als de download al heeft plaatsgevonden en u opnieuw wilt downloaden - binnen 30 dagen na de eerste download.

Wilt u alsnog uw luisterboek opnieuw downloaden?
Geen probleem! Neem daarvoor contact op met de klantenservice van uw webshop. Zij kunnen de bestaande downloadlink opnieuw activeren.

In the example above, the name of the web shop is dynamically added to the message, so it will be the actual name of the web shop using the Luisterhuis API.

There are two ways to re-arm (re-enable or reset) the lifetime of a download link:

Through the API: Every time a download link is requested using downloadinfo API, a new (set of) link(s) will be generated, having a new, fresh lifetime of 365 days.
By using the Reseller dashboard for web shops. See Reset a download link in Chapter 8.3 Sales.

Reseller dashboard for web shops

Introduction

Every Luisterhuis web shop client has access to the web based Reseller client dashboard on https://www.luisterhuis.nl/reseller

For testing purposes, the URL is https://stub-www.luisterhuis.nl/reseller. The login credentials are supplied on request.

The Reseller client dashboard offers 5 pages:

Home: news and important information
Sales: transactions and the possibility to reset an already supplied download link, and cancelling an order within 7 days
Invoices: copies of the monthly invoices sent to the reseller
Titles: list of all available audiobooks, including an export function
Publishers: list of publishers who have enabled their audiobook(s) to this reseller, including an export function

Home

Example of the Home page:

Example of Home page

Sales

By default, the Sales page shows all transactions from the current day. It is possible to select Monthly, Quarterly or Yearly views using the Select range-controls.

Use the Search field to find an individual sales transaction based on the Luisterhuis order ID, the reseller order ID, customer name or customer email address. Searching customer name and email address is only possible when the reseller web shop uses these data when ordering an audiobook through the API.

Sales page

To download a sales report, use the Download csv button.

Please note: The csv will contain the selected range. Select the correct Year, Month, Quarter before starting a download.

Reset a download link
Download links generated by the Luisterhuis distribution system have a limited validity. Usually, a fresh download link is valid for 365 days after being generated, and 90 days when the download link has been activated. When an end user waits too long to start (activate) their download, or when they have lost their downloaded files, it is possible to re-activate ("re-arm") an already supplied download link using the Reset button on the Sales page.

Follow these steps to reset a download link:
1	Locate the correct transaction by using the year and period dropdown menu’s or use Search.
2	Doublecheck the username and user email address by hovering over the Reset button with your mouse. A popup dialog appears with extra info.
3	If the correct name appears, click on the reset button. At that moment, the existing download link receives a new expiration date 365 days from the date of resetting.
4	Also, an email will be sent to the reseller customer support address (if known by Luisterhuis). This email contains a copy of the download link(s). This email can be forwarded to the end user if necessary.

Invoices

This page contains an overview of all monthly invoices.

Invoices

Please note that the invoices will be sent (emailed) by CB to the financial contact address at the web shop.

Titles

The Titles page offers an overview of all audiobooks available for the client through the Catalogue API (see Chapter 4).

Titles

This page contains the most essential metadata of the available titles. The Inactive titles button shows all audiobooks that are withdrawn by the publisher.
In addition to the web pages, a csv file with a selection of metadata can be downloaded using the Export to CSV button on the top right.

Please note that the most extensive metadata only is available through the API by means of the API commands for ONIX catalogue retrieval (see Chapter 4).

Publishers

The Publisher page contains a list of all publishers who have released audiobooks for the web shop, including the number of titles.

Publishers

The data can be exported in CSV format using the Export button.
More information about the individual titles (including an export in CVS format) can be found on the Titles-page.

Browser not supported