VLB REST API Specificationsinfo.vlb.de/media/vlb_rest_api_userspecification.pdfVLB REST API...

VLB REST API Specifications

User Documentation for Fetching Metadata, Cover and Multimedia Objects

Version: 1.5

Date: 08.01.2018

Status: Release

VLB REST API Specifications 1 / 79

1. Contents

1. Contents .............................................................................................................. 1

2. Change History .................................................................................................... 5

3. Introduction .......................................................................................................... 6

3.1. Target Group for This Document ................................................................... 6

3.2. Abstract of This Document ............................................................................ 6

3.3. Further Remarks about This Document ......................................................... 6

3.3.1. Metadata Users (including Covers and Media Files) ............................... 6

3.3.2. Cover Data Users ................................................................................... 6

3.3.3. Users of the Media Files ......................................................................... 7

3.4. Alternatives to Data Acquisition through the VLB API ................................... 7

4. VLB API Technology ........................................................................................... 7

4.1. General API Characteristics .......................................................................... 7

4.2. Functionalities for Data Fetches .................................................................... 8

4.3. Changes Relative to the Previous VLB Interfaces ......................................... 8

5. Invocation and Technical Implementation of the Interface ................................... 9

5.1. Communication with the VLB API .................................................................. 9

5.1.1. URL Live Environment ............................................................................ 9

5.1.2. URL Test Environment .......................................................................... 10

5.2. Response Formats ...................................................................................... 10

5.3. Errors ........................................................................................................... 10

5.3.1. Error Codes........................................................................................... 10

5.3.2. JSON Error Codes ................................................................................ 10

5.4. Registration with the API ............................................................................. 11

5.4.1. Access Tokens for API Registrations .................................................... 11

5.4.1.1. Access Tokens per User Group ..................................................... 11

5.4.1.2. Access Tokens for Status Dependent Registration ........................ 11

5.4.1.3. Access Tokens for Status Independent Registration ...................... 12

5.4.2. Authentication ....................................................................................... 12

5.4.3. Status Dependent Registration with Login ............................................ 12

5.4.3.1. Login .............................................................................................. 12

5.4.3.2. Logout ............................................................................................ 13


5.4.4. Queries of Media Objects ..................................................................... 14

5.4.5. Cautions Regarding Access Tokens ..................................................... 14

5.5. Search ......................................................................................................... 14

5.5.1. Description ............................................................................................ 14

5.5.2. Quick Search ........................................................................................ 14

5.5.3. Boolean Search .................................................................................... 16

5.5.3.1. Search Syntax and Boolean Operators .......................................... 17

5.5.3.2. special hints for the usage of the Boolean serach .......................... 18

5.5.4. Stack Search......................................................................................... 18

5.5.5. Request ................................................................................................ 19

5.5.5.1. Response ....................................................................................... 20

5.5.5.2. Example ......................................................................................... 23

5.6. Fetching Product Entries ............................................................................. 24

5.6.1. Request ................................................................................................ 24

5.6.2. Response .............................................................................................. 24

5.6.2.1. JSON-Short .................................................................................... 25

5.6.2.2. JSON-lLong .................................................................................... 28

5.6.2.3. Onix21 Short .................................................................................. 37

5.6.2.4. Onix21 Ref ..................................................................................... 37

5.6.3. Example ................................................................................................ 38

5.7. Call a list of product entries ......................................................................... 46

5.7.1. Request ................................................................................................ 47

5.7.2. Response .............................................................................................. 47

5.8. Fetching Media Files ................................................................................... 47

5.8.1. Description ............................................................................................ 47

5.8.2. Request ................................................................................................ 49

5.8.3. Response .............................................................................................. 49

5.8.4. Example ................................................................................................ 49

5.9. Fetching Covers .......................................................................................... 50

5.9.1. Description ............................................................................................ 50

5.9.2. Request ................................................................................................ 50

5.9.3. Response .............................................................................................. 51


5.10. Index Search ............................................................................................ 51

5.10.1. description ............................................................................................ 51

5.10.2. Request ................................................................................................ 52

5.10.3. Response .............................................................................................. 52

5.10.4. Example ................................................................................................ 52

5.11. Fetching Publisher Data ........................................................................... 53

5.11.1. Description ............................................................................................ 53

5.11.2. Request ................................................................................................ 53

5.11.3. Response .............................................................................................. 53

5.11.4. Example ................................................................................................ 54

5.12. Overview of the Aggregators .................................................................... 55

6. Examples for queries and api response ............................................................ 55

6.1. queries and requests ................................................................................... 55

6.2. API responses ............................................................................................. 57

6.2.1. Response oft he login-function.............................................................. 57

6.2.2. response for metadata-requsets ........................................................... 58

6.2.3. response for cover- and mediaobject calls ............................................ 58

7. Encodings .......................................................................................................... 59

7.1. URL-Encoding ............................................................................................. 59

7.2. HTML-Encoding .......................................................................................... 59

8. Contact .............................................................................................................. 60

9. Appendix ........................................................................................................... 61

9.1. Default Values and Exeptions for Data Fields ............................................. 61

9.2. Remarks to the Fields in Search Result Lists .............................................. 61

9.2.1. productType values ............................................................................... 64

9.2.2. taxKeyEurD / taxKeyEurA / taxKeyChf ................................................ 64

9.2.3. Genre code – additional Information to „Warengruppen-Klassifikation“ /

genre code classification ................................................................................... 65

9.3. Overview of the necessary ONIX code lists ................................................. 66

9.3.1. Fields without Class Assignment .......................................................... 66

9.3.2. audiences ............................................................................................. 66

9.3.3. classifications ........................................................................................ 67

9.3.4. collections ............................................................................................. 67


9.3.4.1. collections – Subtree master ......................................................... 68

9.3.4.2. collections - Subtree identifiers (inside Sub master) ....................... 68

9.3.5. commercialClassifications ..................................................................... 68

9.3.6. contributors ........................................................................................... 69

9.3.7. edition ................................................................................................... 69

9.3.8. extent .................................................................................................... 69

9.3.9. form ....................................................................................................... 70

9.3.10. formFeature .......................................................................................... 71

9.3.11. identifier ................................................................................................ 71

9.3.12. illustration .............................................................................................. 71

9.3.13. languages ............................................................................................. 71

9.3.14. mediaFiles ............................................................................................ 71

9.3.15. prices .................................................................................................... 72

9.3.16. publisher ............................................................................................... 73

9.3.17. relatedProducts ..................................................................................... 73

9.3.18. salesRight ............................................................................................. 74

9.3.19. texts ...................................................................................................... 74

9.3.20. titles ...................................................................................................... 74

9.3.21. websites ................................................................................................ 74

9.3.22. wholesalers ........................................................................................... 75

9.3.23. publisherData ........................................................................................ 75

9.3.24. containeditems ...................................................................................... 75

9.3.25. look-up-table for the detailview Detailansicht ........................................ 76

9.3.25.1. audiences – audienceClassification .............................................. 76

9.3.25.2. classifications – schemeName ..................................................... 76

9.3.25.3. classifications – sourceName ....................................................... 77

9.3.25.4. prices - priceTypeGroup .............................................................. 77


2. Change History

Date Version Change Remarks

02.06.2014 0.5 Limitation to at most 250 en-tries / page

internal

06.06.2014 0.6 User groups for metadata, cov-er and media files inserted

20.08.2014 0.7

- Hierarchy and collection search by ID (was chapter 14) removed. - Boolean search on collections and hierarchies adapted - List of available MMO types extended - “Author” replaced by “Contrib-utor” in the “json format” search results list - Release for test phase

20.03.2015 0.8

- commodity group in search lists - ISBN (with hyphens) and ISSN integrated in search lists

18.05.2015 0.9 - adding Appendix

18.122015 1.0 addition – bundle Darstellung

21.01.2016 1.1 testsystem only temporarily available

API cus-tomers should use the produc-tive system for testing purpose

05.02.2016 1.2 selection criteria for bundle products

bundle products with sales tax splitting can now be selected by a boolean search

03.05.2016 1.3 small adaptions. Update of the cover size table

22.06.2016 1.4 Bundle EUR-AT price added Chapter 5.6.3 Ex-ample – bundle product added

08.01.2018 1.5 New functionality to acll a list of detailed product entries

New func-tionality and text correc-tions.


3. Introduction

3.1. Target Group for This Document

The following specifications are intended for service providers for programming the

accesses to the VLB data, the cover and media files. Programming knowledge of

how to integrate the REST interface is presupposed.

3.2. Abstract of This Document

o General explanations regarding API technologies will be given in chapters 3

and 4

o Chapters 5.1, 5.2 and 5.3 describe the implementation of the interface as well

as error messages and return formats, URLs to call the interface in the test-

and live-system.

o Chapter 5.4 informs about logging into the interface.

o Search tools and search lists will be described in chapter 5.5, also containing

Boolean search and fields in search lists in two JSON formats.

o Chapter 5.6 describes fetching product entries in different formats.

o Chapter 6 contains examples for calling the interface

3.3. Further Remarks about This Document

Future versions of the API documentation will refer more and more to the online help

of VLB.

The document contains pointers on using the API

1. for users of the metadata, covers and media files

2. for users who are only authorized to invoke cover data (cover API)

3. for users who are only authorized to invoke media files (including covers)

4. API fields that are not listed in the current specification should not be used.

When getting available within the specification the fields are to be regarded.

The chapters that are relevant for each of these user groups are listed below.

3.3.1. Metadata Users (including Covers and Media Files)

Users who fetch metadata of any kind must be familiar with the entire document.

3.3.2. Cover Data Users

Users who are only authorized to fetch covers are asked please to observe the fol-

lowing sections:

- Section 1 Contents to section 5.3 Errors

- Section 5.4 Registration with the API


- Section 5.4.1 Access Tokens for API Registrations

- Section 5.4.1.1 Access Tokens per User Group

- Section 5.4.1.3 Access Tokens for Status Independent Registration

- Section 5.9 Fetching Covers

3.3.3. Users of the Media Files

The following sections are relevant for users who access all media files:

- Section 1 Contents to section 5.3 Errors

- Section 5.4 Registration with the API

- Section 5.4.1 Access Tokens for API Registrations

- Section 5.4.1.1 Access Tokens per User Group

- Section 5.4.1.3 Access Tokens for Status Independent Registration

3.4. Section 5.7 Call a list of product entries

To retrieve several detailed product informations in one call as a list a function has to

be used that needs a list of product IDs (uuid) similar to the stack search.

The order of the uuid’s in the request corresponds to the order of the products in the

result list.

For the stack call a HTTP POST request has to be used where the uuid’s are given in

the payload:

{

"ids": [

“<value>”,

“<value>”,

“<value>”,

…

]

}

3.4.1. Request

URL:

http://api.vlb.de/api/v1/product/multipleProducts

Protocol:

HTTP/S

Authentication necessary:

yes

Request Parameter:

none


3.4.2. Response

HTTP-StatusCode: 200

Format: String

Content:

The following summary list only the most important parameters :

id: The ID of the product to be displayed. The ID is passed in the search

results in the field “id” and can be referenced from there.

version: The version in which a data record is available. This number is incre-

mented each time the record is changed.

composites: The individual blocks (audiences, contributors, etc.) are designated as

composites here. These generally follow ONIX structure and contain

parameters with meaningful names.

There is only one response format - JSON. A response format other than JSON ist

not possible (no JSON-short, no ONIX).

[

product {

...

},

product {

...

},

....

]

- Fetching Media Files

3.5. Alternatives to Data Acquisition through the VLB API

VLB data can be acquired not only through the VLB API but also in ONIX format

through an FTP access.

The media files (with covers) have to be acquired by the FTP in addition to the ONIX

data.

If you would like the access to the ONIX data or media files to be installed, please

turn to MVB customer service (contact data in chapter “8 Contact”).

4. VLB API Technology

The VLB API is based on REST technology (Representational State Transfer). This

results in changes and advantages in application and performance relative to the

previously used SOAP technology.


4.1. General API Characteristics

The general characteristics of the VLB API are as follows:

- The authentication method used by the VLB interface is OAuth2 with a sim-

plified authorization procedure that uses a token for further communication.

- Each data record contains a unique ID, which is a 32 place alphanumeric

GUID (globally unique identifier).

- The following two basic data formats are available: JSON(Java Script Object

Notation) and ONIX 2.1.

- The JSON format is packed in a JSON wrapper that returns per search the

total number of search results, the total number of pages, the number of

search results per page and the page number.

- The interface falls back on the customary HTML Status and Error Codes for

error handling. Errors are specified more precisely in the result.

- The VLB REST API contains version information in the URL so that – when

the API is upgraded – existent applications can also be used during a transi-

tion phase before they have to be changed. This feature can be used to simpli-

fy handling of multiple versions.

- The API can be used both for individual single user solutions and for web-

shops. The basic configuration is done by MVB.

4.2. Functionalities for Data Fetches

The functionalities offered by the VLB REST API, which are similar to those of the

foregoing VLB APIs, are as follows:

- Login / Logout

- Various search methods (quick search, Boolean search, hierarchy and collec-

tions search)

- Return in two formats (JSON and ONIX 2.1)

- Search list in two different field composites

- Article information can be fetched in two field composites on the basis of an ID

- Fetch of the URL for the article cover

- Fetch of the URL for further media files

- Fetch of publisher information on the basis of a publisher ID

- Invocation of indices for various fields

- separate request of active and archived titles possible (fee-based activation on

request of the customer)


4.3. Changes Relative to the Previous VLB Interfaces

The following changes since the previous VLB interfaces must be taken into account

when migrating to the new API:

- The API URL has changed and now contains version information;

- Each record contains a unique ID, which is a 32 place alphanumeric GUID

(globally unique identifier);

- The VLB REST API no longer subdivides the data sources into databases

which can be queried separately; rather, a new field, “aggregator”, can be ad-

dressed during the search and selection by data source is now possible.

Some field lengths and data types have changed (e.g. IDs which used to be issued

numerically are now issued in a 32 place alphanumeric value). The authentication

procedure has been changed to OAuth2.

5. Invocation and Technical Implementation of the Interface

5.1. Communication with the VLB API

The VLB REST API is invoked by means of URLs within which servers, function and

parameters have to be defined. The request header must state the access token,

When products are being queried, it must also state the return format [JSON (short,

long), Onix (short, ref)].

General URL format:

http://api.vlb.de/api/v1/<function>?<parameter>

The API can be called by HTTP as well as by HTTPS. When changes in function

invocations are incompatible with the previous version, the version number (“v1” in

the foregoing example) has to be incremented (v2, v3, etc.). This applies particularly

to field deletions and type changes because these also require adaptations to the

client system.

Every function invocation can return an error. Error codes are listed in chapter 5.3.1

Error Codes. In addition, error messages in plain text are issued in JSON.

The requests mentioned next all use an HTTP GET unless something else is stated.

5.1.1. URL Live Environment

The live environment of the API for productive operation can be reached under the

following URL:

http://api.vlb.de/api/v1/<function>?<parameter>

http://api.vlb.de/api/v1/%3cfunction%3e?%3cparameter

http://api.vlb.de/api/v1/%3cfunction%3e?%3cparameter


The live environment should be used for the development phase as well as for the

productive usage at the customer.


5.1.2. URL Test Environment

The testystem will be temporarily available for testing new functionalities. Before the

testsystem will be activated the API customers will be informed about the availablity

for testing. .

http://test-api.vlb.de/api/v1/<function>?<parameter>

5.2. Response Formats

The “Content-Type” field of the HTTP header states the format in which the parame-

ters are to be passed. Its “Accept” field defines the format of acceptable responses

and must be set. The formats supported by an endpoint are stated in the description

of the endpoint.

Response Formats:

- application/json-short used for the response of the “JSON-Short” format

- application/json used for the response of the “JSON-Long” format

- application/onix21-short returns ONIX21 in short format (default)

- application/onix21-ref returns ONIX21 in reference format (default)

5.3. Errors

5.3.1. Error Codes

The error codes returned by the API are based on the standard http errors.

- 400 Bad request: format error in request message

- 401 Unauthorized: valid authentication required for processing

- 403 Forbidden: request forbidden in given form

- 404 Not found: it was not possible to find the resource

- 500 Internal server error - applies to general status errors

Calling archived articles using a token without archived product access, will return an

error “401 – unauthorized”.

5.3.2. JSON Error Codes

Further error information is issued in JSON format in the response body, in addition

to the HTTP error codes. These messages are structured as follows:

{

"error": "<error_code>",

"error_description": "<error_description>"

http://test-api.vlb.de/api/v1/%3cfunction%3e?%3cparameter


}

The possible error codes are:

- invalid_token: access token received is not valid

- product_blocked: product not released for display

- no_permission: insufficient authorization level of given token.

For further error messages please check chapter 6.2 API responses.

5.4. Registration with the API

The API works with an access token for authentications on the basis of the REST

technology and the OAUTH2 procedure. The access token has to be used for each

query submitted to the API.

5.4.1. Access Tokens for API Registrations

Tokens for status dependent registrations are generated for single-user solutions.

Tokens for status independent registrations are generated for webshop solutions.

5.4.1.1. Access Tokens per User Group

Depending on the user group in question, an access token can authorize the user to

fetch

- metadata and media objects including covers

- only media objects including covers

- only cover files

- only metadata

- address data

5.4.1.2. Access Tokens for Status Dependent Registration

Single-user applications must start by logging in; then the required access token is

generated. This token is valid only for this particular login of the application.

A login / password combination allows a certain number of parallel registrations (=

generation of access tokens). When this maximum number is reached, first an ac-

cess token must be “returned” (= “released”) before a new token can be generated.

This maximum number of parallel API logins for the given user/account is set by MVB

customer service.

In the case of a single-user application, the API has set a defined timeout of

60 minutes of inactivity, in which case the token status is set to “invalid”. Within the

first 20 minutes an acidity on the API does not reset the timeout. Within the last 40

minutes any activity on the API will reset the timeout to 60 minutes.


5.4.1.3. Access Tokens for Status Independent Registration

Webshop applications and other applications with an indefinite number of data users

are provided with an access token that allows an unlimited number of parallel appli-

cations. A previous login is not necessary. Access to media files and address data

may be restricted according to authorization level (accounting of customer account).

The token can be provided via the MVB customer service.

5.4.2. Authentication

In the case of all requests, with the sole exception of a login, access is authenticated

by means of the access token. This token can be passed on in two different ways:

1. HTTP authorization header with value “Bearer” followed by the access token

http://api.vlb.de/api/v1/product/29ef901373fb48bea8865948c75af64f

2. URL parameter access_token

http://api.vlb.de/api/v1/logout?access_token=98592fc6-61e6-4ed2-8f9e-f3fe7700bd79

If authentication is not successful, an HTTP 401 is returned with the following JSON format.

{

"error": "invalid_token",

"error_description": "Invalid access token: 98592fc6-61e6-4ed2-8f9e-f3fe7700bd79"

}

5.4.3. Status Dependent Registration with Login

5.4.3.1. Login

Login is needed for applications such as merchandise management and single-user

research systems. The user needs a login-password combination to register with the

API. Successful login is followed by system generation of an access token.

Login Request

The user is logged in and receives a valid access token.

http://api.vlb.de/api/v1/product/29ef901373fb48bea8865948c75af64f

http://api.vlb.de/api/v1/logout?access_token=98592fc6-61e6-4ed2-8f9e-f3fe7700bd79


URL: The login functionality with which the API generates the access token is invoked by

means of the following URL functions:

Live: https://api.vlb.de/api/v1/login/

Protocol: HTTPS

Method: POST

Authentication: Not required

Request Parameters: None

Request Payload:

JSON with the following attributes:

- username your username

- password: your password

Example: {

"username": "your username",

"password": "your password"

}

Response:

HTTP StatusCode: 200

Format: String

Content: access token

5.4.3.2. Logout

The access token passed on with the request is deregistered by the system. See

section 5.4.1.2 Access Tokens for Status Dependent Registration.

URL:

http://api.vlb.de/api/v1/logout

Protocol: HTTP/S

Authentication required

Request Parameters: None

Response:


Format: None

Content: No

https://api.vlb.de/api/v1/login/

http://api.vlb.de/api/v1/logout/


5.4.4. Queries of Media Objects

For reasons of security, fetches of cover objects and media files require a separate

access token which has to be generated in the manner described above. See section

5.4.1.3 Access Tokens for Status Independent Registration.

5.4.5. Cautions Regarding Access Tokens

Access tokens allow access to the VLB system without further authentications. Con-

sequently, the tokens for the cover and media objects must be separate from the to-

kens for fetches of metadata. Make sure that the access tokens cannot be copied or

viewed by any third party, say, for example, with the help of a proxy.

5.5. Search

5.5.1. Description

The VLB API provides the following types of search which are also offered on VLB

online (www.vlb.de):

- Quick Search

- Boolean Search

- Stack Search

- Index Search (see section 5.10 Index Search)

Stopwords are basically excluded from searches. In English these are words such as

“a”, “and”, ”is” and “the” because they are regarded as useless to a search. German

stopwords are a, al, das, dem, den, der, die, ein, eine, einem, einen, einer, eines, el,

l, la, le, les, lo, the, un, una, une, uno.

When using quotation marks within a serach to set an expression the ASCII 22 sym-

bol has to be used. (for example: st=“holiday on the beach”)

5.5.2. Quick Search

Quick searches cover the following fields:

- Keywords (list from the publisher, German National Library (DNB) keywords)

- Titel and subtitle

- Series- and hierarchy title

- Author

- Publisher


- Identifier (ISBN, GTIN, ISSN, ÖSB-number, order number etc.)

- thema-subject

- genre Code index

- genre code text (for example: Erzählende Literatur)

- journal groupname (for example: Chemische Industrie, Kunststoffe)

- Collection-ID

- X number for hierarchies


5.5.3. Boolean Search

Boolean searches use the Boolean parameters known from the VLB.

Category Fields Searched in the Index Remarks

ST See fields of the quick-search 5.5.2 Keyword

AU contributors Author

SW keywords

Keyword; receives function from for-mer SS; searches through keywords from the publisher and DNB key-words

TI title title

VL publisher, publisher-Id publisher

IS isbn, gtin, issn, legacyId, proprietary-Ids

Identifiers

PR currentPriceDe Price in Germany

EJ publicationDate publication date of the article

WG genreCode genre code preceded by genre code index; truncation is allowed. (see also 5.5.3.2)

SP language language

AD modificationDate Date of most recent change (yyyymmdd)

ZD creationDate yyyymmdd

TH themaSubject themaQualifier

Thema-Codes: both searches by sub-jects and qualifiers and truncation are possible (e.g. TH=A finds all titles which are classified with “A”; TH=A* finds all titles with theme classifica-tion that begins with “A”, i.e. AB, AF, AG; AFC, AFH etc.; quite the same applies to qualifiers.)

PF productFormId Product form (ONIX-Codes); trunca-tion is possible (PF=D* gives all digi-tal products)

PT productType Using the boolean parameter „PT“ products with bundle classification an sales tax splitting can be selected. The parameter is case-sensitive: a.:multi-Bundles PT=multiBundle b.:duo-Bundles PT=duoBundle c.:alle MWST splitting Bundles PT=*Bundle see also 9.2.1 productType


RH collection / hierarchy title, collection / hierarchy ID

This category covers both collection and hierarchy searches. The first character of the key indicates which type of search applies.

The category can be entered with any combination of upper and lower case letters;

no blanks allowed before or after equals signs.

One can omit the category statement (for the first category); then ST is selected au-

tomatically.

5.5.3.1. Search Syntax and Boolean Operators

The category statement is followed by one or more search arguments, which are

separated by blanks. If more than one search argument is supplied, these are nor-

mally connected by logical AND (in the same field of the category, but not neces-

sarily in the same row, inasmuch as a field can have two or more values).

Example: au=Karl May

finds all works whose authors, publishers, etc. taken together contain a “Karl”

and a “May”, including, of course, those by Karl May himself.

Diacritical marks (accents, etc.) need not be entered, for they are normalized auto-

matically. The difference between upper and lower case can likewise be ignored.

German Umlauts are set to their 2-letter equivalents (ä <-> ae, ö <-> oe, ü <-> ue).

German “ß” is reset to “ss” (which is equivalent).

Search texts in quotation marks (phrases), are searched in the given order.

Example: au="May, Karl"

finds all the works by Karl May, and only these works, given that names of per-

sons are stored in this form (last name, comma, space, first name(s))

When two or more categories (separated by blanks) are stated, these are automati-

cally connected with logical AND.

Example: ti=gymnastik pf=BC sp=ger

finds all German language pocket books with “gymnastik” in the title.

Alternatively, categories can also be connected explicitly with AND / OR and placed

in parentheses as required.

Example: ti=gymnastik or ti=turnen

finds all works with “gymnastik” or “turnen” in the title.

Example: au=rowling and (pf=AJ or pf=DG)

finds all works that have “rowling” as a contributor and are downloadable as an

audio file or exist as an e-book (or both).


Operators are not recognized as such when they appear within a chain of search ar-

guments. For example, "ti=gymnastik or turnen" does not lead to the desired result;

rather, one must repeat the category, such as “pf” in the preceding example.

Particular values can be explicitly excluded from a search by preceding them with

“NOT”. Then the search is restricted to the works that do not contain these values.

Example: ti=not fish not meat

finds all works with neither "fish" nor "meat" in the title.

The Boolean operators UND / AND, ODER / OR bzw. NICHT / NOT are allowed. The

corresponding characters are not allowed.

Search arguments that contain any symbols for Boolean operators must be enclosed

in quotation marks (ASCII 22) so that these symbols are not interpreted as Boolean

operators.

Example: ti="not fish not meat"

finds all the works with the phrase "not fish not meat" in the title.

The caret symbol (^) is used to search periods.

Example: search=AD=20150319^20150321 meaning that the start date is included and

the end date excluded.

A datefield search uses the ONIX-dateformat (YYYYMMDD) with 4 (YYYY), 6

(YYYYMM) or 8-figure. Alternatively the german datemformat can be used

(DD.MM.YYYY) which is only allowed in a 8-figure format. A wildcard search can’t be

used for the german dateformat. The ONIX-datumsformat can only be combined with

wildcard in 4 or 6 figure format.

5.5.3.2. special hints for the usage of the Boolean serach

When a search using Boolean parameters is done for some fields special treatment is nec-

essary:

o genreCode search

o search fort he genreCode -index: WG=1???

(this example sets a search for hard-/softcover Titles - WG-Index 1)

o search for the genre-code: WG=?250

(in this case search for genre-code 250 - Kinderbücher bis 11 Jahre)If a

search with quotation marks is performed, the quotation mark ASCII

Code 22 has tob e used – for example "hello world".

5.5.4. Stack Search


A list of up to 500 ISBNs can be passed to the stack search function. A stack search

can be combined with Boolean parameters.

An HTTP POST must be used for a stack search. Then ISBNs can be stated in the

payload and are expected there as follows:

{

"content": [

{

"isbn": "<value>",

},

{

"isbn": "<value>",

},

]

}

5.5.5. Request

URL:

http://api.vlb.de/api/v1/products?page=<pageno>&size=<size>&[sort=<column>]&[direction=<direction>]&search=[<value>][&status=<status>][&source=<source>]

Protocol:

http

Authentication:

Required

Request Parameters:

page: The number of the page to be outputted (begins with 1).

size: The maximum number (1 - 250) of products per page

sort (optional): The output column by which the search results are to be

sorted. Possible values would be:

- identifier

- author

- titleAndSubtitle

- publisher

- publisherMvbId

- publicationDate

- availabilityStatePublisher

- availabilityStateFeed

- price

- createDate

- lastChangeDate

http://api.vlb.de/api/v1/products?page=%3cpageno%3e&size=%3csize%3e&%5bsort=%3ccolumn%3e%5d&%5bdirection=%3cdirection%3e%5d&search=%5b%3cvalue%3e%5d%5b&status=%3cstatus%3e%5d%5b&source=%3csource%3e%5d

http://api.vlb.de/api/v1/products?page=%3cpageno%3e&size=%3csize%3e&%5bsort=%3ccolumn%3e%5d&%5bdirection=%3cdirection%3e%5d&search=%5b%3cvalue%3e%5d%5b&status=%3cstatus%3e%5d%5b&source=%3csource%3e%5d


- productType

- state

direction (optional): Direction of sort: asc (ascending) or desc (descending).

search (optional): A Boolean search phrase (encoded URL). If not stated,

then the search is for all available products. Fields can be

explicitly searched via Boolean parameters. If the search

phrase does not contain any limiting search fields, then

the search is conducted in the quick search fields.

status (optional): Active and / or inactive (archived) titles. If no status set in

request active and archived titles will be selected

source (optional): Defines the aggregator of the data to be delivered. Can be

linked without limitations. If no source given all sources will

be selected. See Section 5.12

5.5.5.1. Response


Format: JSON (short or long)

Content: The search results (basic data). The most important fields:

id: The (internal) unique ID of the product

version: The version number of the product (for internal purposes)

identifier: The main identifier of the product (usually ISBN13). Ac-

cording to the selection the identifier can occur several

times; it is unique per aggregator.

sort: Parameters for sorting the results list

direction: ascending (ASC) or descending (DESC)

property: The results column by which the results are to be sorted

(this is always one of the content columns)

ascending: true, if direction = "ASC", else false

totalPages: The total number of pages in the search result

lastPage: true if this is the last page of the search result, else false

numberOfElements Number of search results displayed on this page

totalElements: Total number of search results

firstPage: true if this is the first page of the search results

size: The maximum requested number of products

number: The current page number. Begins with 0 – thus it corre-

sponds to search parameter page −1


JSON-Short Response: {

"content": [

{

"id": <value>,

"version": 1,

"identifier": <value>,

"isbn": <value>,

"issn": <value>,

"gtin": <value>,

"osbnr": <value>,

"bestellnummer": <value>, orderNumber

"umbreitNummer": <value>, UmbreitNumber

"cbzNummer": <value>, cbzNumber

"edisNummer": <value>, edisNumber

"schulbuchBestellnummer": <value>, schoolBookOrderNumber

"author": <value>,

"title": <value>,

"subTitle": <value>,

"publisher": <value>,

"publisherMvbId": <value>,

"publicationDate": <value>,

"edition": <value>,

"availabilityStatePublisher": <value>,

"availabilityStateFeed": <value>,

"productType": <value>,

"priceEurD": <value>,

"priceEurA": <value>,

"priceCHF": <value>,

"unpricedItemCode": <value>,

"fileFormat": <value>,

"referencePriceDE": <value>,

"createDate": <value>,

"lastModifiedDate": <value>,

"state": <value>,

"collections": <value>,

"productFormId": "<value>"

},

],

"last": <value>,

"totalElements": <value>,

"firstPage": <value>,

"totalPages": <value>,

"lastPage": <value>,

"first": <value>,

"sort": [

{

"direction": "<direction>",

"property": "<property>",

"ignoreCase": "<property>",

"ascending": <ascending>

}

],

"numberOfElements": <numberOfElements>,

"size": <size>,

"number": <number>

}

JSON-Long Response: {

"content": [

{

"id": "<value>",

"version": <value>,

"identifier": "<value>",

"gtin": "<value>",

"osbnr": <value>,

"bestellnummer": "<value>",

"umbreitNummer": <value>,

"cbzNummer": <value>,

"edisNummer": <value>,

"schulbuchBestellnummer": "<value>",


"title": "<value>",

"subTitle": "<value>",

"publisher": "<value>",

"publisherMvbId": "<value>",

"publicationDate": "<value>",

"edition": "<value>",

"availabilityStatePublisher": "<value>",

"availabilityStateFeed": <value>,

"priceEurD": <value>,

"priceEurA": <value>,

"priceCHF": <value>,

"unpricedItemCode": "<value>",

"createDate": "<value>",

"lastChangeDate": "<value>",

"productType": "<value>",

"state": "<value>",

"collections": [<values>],

"productFormId": "<value>",

"contributors": [

{

"type": "<value>",

"firstName": "<value>",

"lastName": "<value>",

"groupName": <value>

}

],

"priceAdditionEurD": <value>,

"taxEurDInfo": <value>,

"taxKeyEurD": "<value>",

"priceCaEurD": <value>,

"priceAdditionEurA": <value>,

"taxEurAInfo": <value>,

"taxKeyEurA": "<value>",

"priceCaEurA": <value>,

"priceAdditionChf": "<value>",

"taxChfInfo": <value>,

"taxKeyChf": "<value>",

"priceCaChf": <value>,

"contentThemes": [

"<value>"

],

"additionThemes": [

"<value>"

],

"keyWords": [<values>],

"onSaleDate": <value>,

"language": "<value>",

"sigl": "<value>",

"aggregatorId": <value>,

"coverUrl": "<value>",

"shortDescription": "<value>",

"mainDescription": "<value>"

},

],

"totalElements": <totalElements>,

"totalPages": <totalPages>,

"firstPage": <firstPage>,

"lastPage": <lastPage>,

"last": <value>,

"sort": [

{

"direction": "<direction>",

"property": "<property>",

"ascending": <ascending>

}

],

"numberOfElements": <numberOfElements>,

"first": <first>,

"size": <size>,

"number": <number>

}


5.5.5.2. Example

In this example, a list of all products is invoked, whereby each page (“size” parame-

ter) is limited to 2 products and the first page is to be displayed.

http://api.vlb.de/api/v1/products?page=1&size=2&sort=identifier&direction=asc

{

"content": [

{

"id": "4d5666384ce04293b18da5fc7f844972",

"version": 1,

"identifier": "SB120136",

"isbn": "978-3-7058-6328-6",

"issn": null,

"gtin": "9783705863286",

"osbnr": null,

"bestellnummer": "SB120136",

"umbreitNummer": null,

"cbzNummer": null,

"edisNummer": null,

"schulbuchBestellnummer": null,

"title": "Kek 2. Das Lesebuch. Basisteil",

"subTitle": "SBL / 0101 seit 2005/06; Kl. 2",

"publisher": "Veritas Verlag [50]",

"publisherMvbId": "5106488",

"publicationDate": null,

"edition": null,

"availabilityStatePublisher": "20",

"availabilityStateFeed": "01",

"productType": "undefined",

"priceEurD": 13.09,

"priceEurA": 13.09,

"priceCHF": null,

"unpricedItemCode": null,

"referencePriceDE": false,

"createDate": "23.03.2015",

"lastModifiedDate": "23.03.2015",

"state": "active",

"collections": null,

"productFormId": null,

"contributors": [

{

"type": "A01",

"firstName": "Gabriele Bugram",

"lastName": "Bauer-Herland",

"groupName": null

}

],

"priceAdditionEurD": "UVP",

"taxEurDInfo": null,

"taxKeyEurD": "0",

"priceCaEurD": null,

"priceAdditionEurA": "UVP",

"taxEurAInfo": null,

"taxKeyEurA": "0",

"priceCaEurA": null,

"priceAdditionChf": "UVP",

"taxChfInfo": null,

"taxKeyChf": "0",

"priceCaChf": null,

"themaSubjects": null,

"themaQualifiers": null,

"keyWords": [

"DEUTSCH-LESEN"

],

"onSaleDate": null,

"language": null,

"sigl": [

"A-BLC"

],

http://api.vlb.de/api/v1/products?page=1&size=2&sort=identifier&direction=asc


"aggregatorId": "5001015",

"coverUrl": null,

"shortDescription": null,

"mainDescription": "\n",

"biographicalNote": null,

"genreCode": null

}

],

"totalPages": 1,

"firstPage": true,

"totalElements": 1,

"lastPage": true,

"last": true,

"sort": [

{

"direction": "ASC",

"property": "identifier",

"ignoreCase": false,

"ascending": true

}

],

"numberOfElements": 1,

"first": true,

"size": 250,

"number": 0

}

5.6. Fetching Product Entries

Product entries can be fetched in detail by means of the 32 place product ID, in the

event that the information in the search results list is insufficient. Three output for-

mats are normally available for this (JSON short, JSON long, and ONIX).

5.6.1. Request

URL: http://api.vlb.de/api/v1/product/<id>[/<id-type>]

Protocol: HTTP/S

Authentication: required

Request Parameters

id: The ID of the product to be displayed. The ID is passed in

the search results in the field “id” and can be referenced

from there.

id-type (optional): The type of the ID passed. If none is stated, the unique ID

is passed as default. The possible values are:

- gtin

- isbn13

- ean

5.6.2. Response

http://api.vlb.de/api/v1/product/%3cid%3e%5b/%3cid-type%3e



Format: String

Content:

Only the most important parameters are presented in the following

id: The unique ID of a data record. Every subentity provides

an id. This is a hash value with 32 places.

version: The version in which a data record is available. This num-

ber is incremented each time the record is changed.

composites: The individual blocks (audiences, contributors, etc.) are

designated as composites here. These generally follow

ONIX structure and contain parameters with meaningful

names.

The response for individual product fetches is offered in two different formats: JSON

and ONIX. Two output profiles are available for responses in JSON format.

ONIX only returns data from the VLB; data from other aggregators cannot be fetched

in ONIX format.

5.6.2.1. JSON-Short

The JSON-short profile returns the most important three long texts in their entirety

plus the product’s metadata without detailed publisher information. These long text

fields are as follows:

- short description

- description

- bionote (biographical comments)

The remaining long texts are not contained in the short format.

The detailed publisher information must be imported in JSON short format by means

of the separate function for fetching publisher data (section 5.11). In this case, pub-

lisher data that has already been read in should be kept in intermediate storage so

that this function does not have to be invoked each time this data is needed. {

"id": <value>,


"announcementDate": <value>,

"availabilityDate": <value>,


"titles": [

{

"id": <value>,

"type": <value>,

"subtitle": <value>,

"title": "<value>"

}

],

"thesisType": <value>,

"thesisPresentedTo": <value>,

"thesisYear": <value>,


"countryOfManufacture": <value>,

"availability": <value>,

"availabilityStatusCode": <value>,

"publishingStatus": <value>,


"phonogramYear": <value>,

"phonogram": <value>,

"bisacMainSubject": <value>,

"bicMainSubject": <value>,

"publicationCity": [

"<value>"

],

"publicationCountry": <value>,

"edition": {

"id": <value>,

"type": <value>,

"number": <value>,

"text": <value>,

"release": null

},

"form": {

"id": <value>,

"type": <value>,

"binding": <value>,

"description": <value>,

"detail": <value>,

"diameter": <value>,

"height": <value>,

"width": <value>,

"weight": <value>,

"thickness": <value>,

"packaging": <value>,

"productContentType": [<values>]

},

"extent": {

"id": <value>,

"duration": <value>,

"durationUnitCode": <value>,

"fileSize": <value>,

"fileSizeUnitCode": <value>,

"mapScale": <value>,

"numCds": <value>,

"numTracks": <value>,

"numIllustrations": <value>,

"illustrationText": <value>,

"pages": <value>,

"pagesRoman": <value>,

"pagesArabic": <value>,


"epubTypeDescription": <value>,

"drm": "<value>"

},

"audiences": [

{

"id": <value>,

"type": <value>,

"value": <value>,

"rangeCode": <value>,

"ageFrom": <value>,

"ageTo": <value>,


"codeTypeName": <value>,

"range": <value>

}

],

"contributors": [

{

"id": <value>,

"sequence": <value>,

"type": <value>,

"sequenceWithinRole": <value>,

"firstName": <value>,

"lastName": <value>,

"groupName": <value>,


"dnbId": <value>,

"professionalAffiliation": <value>,

"professionalPosition": <value>,

"biographicalNote": <value>,

"dateOfBirth": <value>,

"dateOfDeath": <value>,

"dateOfBirthFormat": <value>,

"dateOfDeathFormat": <value>,

"language": <value>,

"fullName": "<value>"

}

],

"classifications": [

{

"id": <value>,

"type": <value>,

"systematicVersion": <value>,

"code": <value>,

"value": <value>,

"schemeName": <value>,

"main": <value>

}

],

"identifiers": [

{

"id": <value>,

"typeName": <value>,

"type": <value>,

"value": "<value>"

}

],

"languages": [

{

"id": <value>,

"type": <value>,

"value": "<value>"

}

],

"prices": [

{

"id": <value>,

"type": <value>,

"country": <value>,

"currency": <value>,

"validFrom": <value>,

"validUntil": <value>,

"state": <value>,

"taxRate": <value>,

"value": <value>,

"typeQualifier": <value>,

"typeDescription": <value>,

"minimumQuantity": <value>,

"referencePrice": <value>,

"fixedRetailPrice": <value>

}

],

"publishers": [

{

"id": <value>,

"type": <value>,

"name": "<value>”,

"nameCodeType": <value>,

"publisherId": "<value>"

}

],

"salesRights": [

{

"id": <value>,

"type": <value>,

"country": <value>,

"region": <value>,

"territory": "<value>"

}

],


"texts": [

{

"id": <value>,

"type": <value>,

"formatCode": <value>,


"value": <value>,

"linkType": <value>,

"link": <value>,



"assetFileId": <value>,

"internalUrl": <value>,

"externallyGenerated": <value>

}

],

"illustrations": [

{

"id": <value>,

"type": <value>,


"number": <value>

},

{

"id": <value>,

"type": <value>,


"number": <value>

}

],

"formFeatures": [<values>],

"wholesalers": [<values>],

"mediaFiles": [<values>],

"webSites": [<values>],

"commercialClassifications": [

{

"id": <value>,

"type": <value>,

"value": "<value>"

}

],

"collections": [<values>],

"relatedProducts": [

{

"id": <value>,

"type": <value>,

"productIdType": <value>,

"productIdValue": <value>,

"productForm": <value>,

"productFormDetail": <value>

}

],

"createdDate": <value>,


"ranking": <value>,

"active": <value>

5.6.2.2. JSON-lLong

The JSON long format contains all of a product’s metadata and long text fields in

their entire length. In regard to performance (execution and response times) one

must keep in mind that the long texts in VLB can be of very great length because

there are no restrictions on the number of characters in the additional long text fields.

For access tokens for status independent registrations the composite “publisherData”

is only available after activation by MVB customer service (5.4.1.3 Access Tokens for

Status Independent Registration)


{

{

"id": <value>,

"notificationType": <value>,

"bvdId": <value>,

"aggregatorId": <value>,

"providerId": <value>,


"announcementDate": <value>,

"availabilityDate": <value>,


"titles": [

{

"id": <value>,

"type": <value>,


"title": <value>

},

{

"id": <value>,

"type": <value>,


"title": <value>

}

],

"thesisType": <value>,

"thesisPresentedTo": <value>,

"thesisYear": <value>,

"countryOfManufacture": <value>,

"availability": <value>,

"availabilityStatusCode": <value>,

"publishingStatus": <value>,

"publishingStatusNote": <value>,


"noContributor": <value>,

"phonogramYear": <value>,

"phonogram": <value>,

"bisacMainSubject": <value>,

"bicMainSubject": <value>,


<value>

],

"publicationCountry": <value>,

"tradeCategory": <value>,

"edition": {

"id": <value>,

"type": <value>,

"number": <value>,

"text": <value>,

"release": <value>

},

"form": {

"id": <value>,

"type": <value>,

"binding": <value>,


"detail": <value>,

"diameter": <value>,

"height": <value>,

"width": <value>,

"weight": <value>,

"thickness": <value>,

"packaging": <value>,

"productContentType": <value>,

"numberOfPieces": <value>

},

"extent": {

"id": <value>,

"duration": <value>,

"durationUnitCode": <value>,

"fileSize": <value>,

"fileSizeUnitCode": <value>,

"mapScale": <value>,

"numIllustrations": <value>,


"numTracks": <value>,

"illustrationText": <value>,

"pages": <value>,

"pagesRoman": <value>,

"pagesArabic": <value>,


"epubTypeDescription": <value>,

"drm": <value>,

"drmCode": <value>,

"epubTypeVersion": <value>

},

"zisInfo": <value>,

"audiences": [

{

"id": <value>,

"type": <value>,

"value": <value>,


"ageFrom": <value>,

"ageTo": <value>,



"audienceClassification": "customer_group",

"range": <value>

},

{

"id": <value>,

"type": <value>,

"value": <value>,


"ageFrom": <value>,

"ageTo": <value>,



"audienceClassification": "main_description",

"range": <value>

}

],

"contributors": [

{

"id": <value>,


"type": <value>,

"sequenceWithinRole": <value>,

"firstName": <value>,

"lastName": <value>,

"groupName": <value>,

"dnbId": <value>,

"professionalAffiliation": <value>,

"professionalPosition": <value>,

"biographicalNote": <value>,

"dateOfBirth": <value>,

"dateOfDeath": <value>,

"dateOfBirthFormat": <value>,

"dateOfDeathFormat": <value>,


"webSites": [

{

"id": <value>,

"type": <value>,

"url": <value>,

"description": <value>

}

],

"company": <value>,

"fullName": <value>,

"value": <value>

}

],


{

"id": <value>,

"type": <value>,



"code": <value>,

"value": <value>,


"sourceName": <value>,

"main": <value>

},

{

"id": <value>,

"type": <value>,


"code": <value>,

"value": <value>,



"main": <value>

},

{

"id": <value>,

"type": <value>,


"code": <value>,

"value": <value>,



"main": <value>

},

{

"id": <value>,

"type": <value>,


"code": <value>,

"value": <value>,



"main": <value>

},

],

"identifiers": [

{

"id": <value>,


"type": <value>,

"value": <value>

},

{

"id": <value>,


"type": <value>,

"value": <value>

},

{

"id": <value>,


"type": <value>,

"value": <value>

}

],

"languages": [

{

"id": <value>,

"type": <value>,

"value": <value>

}

],

"prices": [

{

"id": <value>,

"type": <value>,

"country": <value>,

"territory": <value>,




"state": <value>,


"taxRate": <value>,

"taxRatePercent": <value>,

"taxableAmount": <value>,

"taxAmount": <value>,

"taxRate2": <value>,

"taxRatePercent2": <value>,

"taxableAmount2": <value>,

"taxAmount2": <value>,

"value": <value>,



"discountCodeText": <value>,



"priceTypeGroup": <value>,

"fixedRetailPrice": <value>,

"provisional": <value>,

"referencePrice": <value>

},

{

"id": <value>,

"type": <value>,

"country": <value>,





"state": <value>,

"taxRate": <value>,








"value": <value>,










},

{

"id": <value>,

"type": <value>,

"country": <value>,





"state": <value>,

"taxRate": <value>,








"value": <value>,











},

{

"id": <value>,

"type": <value>,

"country": <value>,





"state": <value>,

"taxRate": <value>,








"value": <value>,










},

{

"id": <value>,

"type": <value>,

"country": <value>,





"state": <value>,

"taxRate": <value>,








"value": <value>,










}

],

"publishers": [

{

"id": <value>,

"type": <value>,

"name": <value>,

"adbName": <value>",

"nameCodeType": <value>,

"publisherId": <value>,

"imprint": <value>,

"webSites": []

}

],

"salesRights": [

{

"id": <value>,

"type": <value>,


"country": <value>,

"region": <value>,

"territory": <value>

}

],

"texts": [

{

"id": <value>,

"type": <value>,



"value": <value>,


"link": <value>,



"textPublicationDate": <value>

},

{

"id": <value>,

"type": <value>,



"value": <value>,


"link": <value>,




},

{

"id": <value>,

"type": <value>,



"value": <value>,


"link": <value>,




},

{

"id": <value>,

"type": <value>,



"value": <value>,


"link": <value>,




},

{

"id": <value>,

"type": <value>,



"value": <value>",


"link": <value>,




}

],

"illustrations": [

{

"id": <value>,

"type": <value>,


"number": <value>

}


],

"formFeatures": [

{

"id": <value>,

"type": <value>,

"code": <value>,


"value": <value>

}

],

"wholesalers": [

{

"id": <value>,

"sigl": <value>,

"orderNumber": <value>

},

{

"id": <value>,

"sigl": <value>,


},

{

"id": <value>,

"sigl": <value>,


},

{

"id": <value>,

"sigl": <value>,


},

{

"id": <value>,

"sigl": <value>,


}

],

"mediaFiles": [

{

"id": <value>,

"type": <value>,

"format": <value>,


"value": <value>,

"fileDate": <value>,

"imageResolution": <value>,



"link": <value>

},

{

"id": <value>,

"type": <value>,

"format": <value>,


"value": <value>,

"fileDate": <value>,

"imageResolution": <value>,



"link": <value>

}

],

"webSites": [

{

"id": <value>,

"type": <value>,

"url": <value>,

"description": <value>

}

],


{

"id": <value>,


"type": <value>,

"value": <value>

}

],

"collections": [

{

"id": <value>,

"master": {

"id": <value>,

"type": "series",

"identifiers": [

{

"id": <value>,


"type": <value>,

"productIdentifierType": <value>,

"value": <value>

}

],

"title": <value>,

"abbreviatedTitle": <value>,


"publisherId": <value>,


"active": <value>,

"bitNo": <value>,

"deletionDate": <value>,

"concatenateTitle": <value>

},


"levelSequence": <value>,

"titleInCollection": <value>

}

],


{

"id": <value>,

"type": <value>,

"productIdType": <value>,

"productIdValue": <value>,

"productForm": <value>,

"productFormDetail": <value>

}

],

"containedItems": [

{

"id": <value>,

"type": <value>,

"productFormDetail": <value>,

"numberOfPieces": <value>,



"productIdentifierTypeName": <value>,

"productIdentifierValue": <value>,



"country": <value>,


"value": <value>,

"taxRate": <value>,



"title": <value>,

"taxInfo": <value>

},

{

"id": <value>,

"type": <value>,

"productFormDetail": <value>,

"numberOfPieces": <value>,



"productIdentifierTypeName": <value>,

"productIdentifierValue": <value>,




"country": <value>,


"value": <value>,

"taxRate": <value>,



"title": <value>,

"taxInfo": <value>

}

],

"priceRepealDate": null,

"notPriceRefRelevantDate": <value>,

"priceDataDachChangeDate": <value>,

"priceDataInternationalChangeDate": <value>,

"createdDate": <value>,


"active": <value>,

"bitNo": <value>,

"invoiceStatus": <value>,

"bundle": <value>,

"mediumTypeCode": <value>

}

}

5.6.2.3. Onix21 Short

If metadata for a product are not in valid Onix format the API returns an empty Onix

header.

Please consult the appropriate Onix specifications for the exact response parameters

in Onix2.1.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<!DOCTYPE ONIXmessage SYSTEM "http://www.editeur.org/onix/2.1/short/onix-international.dtd">

<ONIXmessage release="2.1">

<header>

<m174>VLB - Demo</m174>

<m175>MVB Marketing- und Verlagsservice des Buchhandels GmbH, 069.1306.550</m175>

<m283>[email protected]</m283>

<m182>20140818</m182>

</header>

<product datestamp="20140730">

<a001>0456cd7cbacb47ee92930e8a85201299</a001>

<a002>03</a002>

<productidentifier>

<b221>02</b221>

….

</OnixMessage>

5.6.2.4. Onix21 Ref

If metadata for a product are not in valid Onix format the API returns an empty Onix

header.

Please consult the appropriate Onix specifications for the exact response parameters

in Onix2.1.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<!DOCTYPE ONIXMessage SYSTEM "http://www.editeur.org/onix/2.1/reference/onix-

international.dtd">


<ONIXMessage release="2.1">

<Header>

<FromCompany>VLB - Demo</FromCompany>

<FromPerson>MVB Marketing- und Verlagsservice des Buchhandels GmbH,

069.1306.550</FromPerson>

<FromEmail>[email protected]</FromEmail>

<SentDate>20140818</SentDate>

</Header>

<Product datestamp="20140730">

<RecordReference>0456cd7cbacb47ee92930e8a85201299</RecordReference>

<NotificationType>03</NotificationType>

<ProductIdentifier>

<ProductIDType>02</ProductIDType>

….

</OnixMessage>

5.6.3. Example

A product that is fetched in JSON short format:

http://api.vlb.de/api/v1/product/5689e439eba040a28190ec6b345af7ef

Result (shows a e-bundle product which was for the reason of a simplified generation

build as a product with similar prices for EUR-DE and EUR-AT. Real products mostly

have different EUR-DE and AT prices, ):

{

"id": "c304571b6ce24b17af006477c74b8340",

"notificationType": "03",

"bvdId": null,

"aggregatorId": null,

"providerId": "5252085",

"publicationDate": "11.04.2016",

"announcementDate": null,

"availabilityDate": null,

"onSaleDate": "11.04.2016",

"titles": [

{

"id": "8c72cd2b2ac94f07898abff265c25765",

"type": "01",

"subtitle": "Rund 450 Funktionen, jede Menge Tipps und Tricks aus der Praxis",

"title": "Excel 2016 Formeln und Funktionen"

}

],

"thesisType": null,

"thesisPresentedTo": null,

"thesisYear": null,

"countryOfManufacture": "DE",

"availability": "20",

"availabilityStatusCode": "IP",

"publishingStatus": "04",

"publishingStatusNote": null,

"unpricedItemCode": null,

"noContributor": false,

"phonogramYear": null,

"phonogram": null,

"bisacMainSubject": null,

"bicMainSubject": null,


"München"

],

"publicationCountry": "DE",

"tradeCategory": null,

"edition": {

http://api.vlb.de/api/v1/product/5689e439eba040a28190ec6b345af7ef


"id": "2256f14c15c54630b916d0500c521347",

"type": null,

"number": null,

"text": null,

"release": null

},

"form": {

"id": "69711515f213449f817b61a5723579bd",

"type": "WW",

"binding": null,

"description": null,

"detail": null,

"diameter": null,

"height": 242,

"width": 193,

"weight": 1390,

"thickness": 40,

"packaging": null,

"productContentType": null,

"numberOfPieces": null

},

"extent": {

"id": "35309d3c4e834256a081c5268d5bec31",

"duration": null,

"durationUnitCode": null,

"fileSize": null,

"fileSizeUnitCode": null,

"mapScale": null,

"numIllustrations": null,

"numTracks": null,

"illustrationText": "Durchgehend zweifarbig",

"pages": null,

"pagesRoman": null,

"pagesArabic": 667,

"fileFormat": null,

"epubTypeDescription": null,

"drm": "none",

"drmCode": null,

"epubTypeVersion": null

},

"zisInfo": null,

"audiences": [],

"contributors": [

{

"id": "e6f2a818da6f444286c9cbc1b13bf6ef",

"sequence": 1,

"type": "A01",

"sequenceWithinRole": 1,

"firstName": "Ignatz",

"lastName": "Schels",

"groupName": null,

"dnbId": null,

"professionalAffiliation": null,

"professionalPosition": null,

"biographicalNote": null,

"dateOfBirth": null,

"dateOfDeath": null,

"dateOfBirthFormat": null,

"dateOfDeathFormat": null,

"language": null,

"webSites": [],

"company": false,

"value": "Schels, Ignatz",

"fullName": "Schels, Ignatz"

}

],


{

"id": "18d81df419034fefbb400554245693ed",

"type": "18",

"systematicVersion": null,

"code": "004",

"value": "Informatik",

"schemeName": null,


"sourceName": "DNB",

"main": false

},

{

"id": "d2c86c9cad38461aa634bddd92cd2512",

"type": "26",

"systematicVersion": "2.0",

"code": "1635",

"value": "Hardcover, Softcover / Informatik, EDV/Anwendungs-Software",

"schemeName": "MainSubject",

"sourceName": null,

"main": true

},

{

"id": "45fd428b9cca4c84bb8d357cd17faf22",

"type": "93",


"code": "UFC",

"value": "Tabellenkalkulation",

"schemeName": "MainSubject",

"sourceName": "Publisher",

"main": true

},

{

"id": "7704a580f54d459896e0c624753cd5af",

"type": "20",


"code": null,

"value": "Excel",

"schemeName": null,

"sourceName": null,

"main": false

},

{

"id": "ae381fec3dbf45f6b75661a7395c81b6",

"type": "20",


"code": null,

"value": "Formeln",

"schemeName": null,

"sourceName": null,

"main": false

},

{

"id": "91c344d4c7db419ca2d5723dfc7d36ae",

"type": "20",


"code": null,

"value": "Funktionen",

"schemeName": null,

"sourceName": null,

"main": false

},

{

"id": "8dc331117c674edc85fe0465b414bd57",

"type": "20",


"code": null,

"value": "Office",

"schemeName": null,

"sourceName": null,

"main": false

},

{

"id": "c3eae6dbbe5a4dc7899014efa0b713d1",

"type": "20",


"code": null,

"value": "Pivot",

"schemeName": null,

"sourceName": null,

"main": false

},

{


"id": "cf9d78a80f524f3bb83f3a1c59a9a326",

"type": "20",


"code": null,

"value": "Tabellen",

"schemeName": null,

"sourceName": null,

"main": false

},

{

"id": "ce2ec0792c7949eb95388c2cedf4aa45",

"type": "20",


"code": null,

"value": "Tabellenkalkulation",

"schemeName": null,

"sourceName": null,

"main": false

},

{

"id": "d7361a5854c24fa6bfd4ecab0bc87c49",

"type": "23",


"code": "FBITANWE",

"value": "Anwendersoftware",

"schemeName": "FBSysNeu",

"sourceName": null,

"main": false

},

{

"id": "ffdd3f2a36fb498c8e6a9272ca6f95ad",

"type": "23",


"code": "INF2016",

"value": null,

"schemeName": "Hanser eLibrary Pakete",

"sourceName": null,

"main": false

},

{

"id": "bee38238bba8464cb929aab48dc69646",

"type": "24",


"code": "00100",

"value": null,

"schemeName": "Artikeltyp",

"sourceName": null,

"main": false

},

{

"id": "c51fd06cdd22413e82fdd5f1c5084cfa",

"type": "24",


"code": "25530",

"value": null,

"schemeName": "Produktgruppe",

"sourceName": null,

"main": false

},

{

"id": "20e4cf3717d542dcb35e025a1384fdd5",

"type": "24",


"code": "55300",

"value": null,

"schemeName": "Verlagssektor",

"sourceName": null,

"main": false

}

],

"identifiers": [

{

"id": "25b19e906e1e40f69f1b30448f82bfe9",

"typeName": null,


"type": "15",

"value": "9783446448025"

},

{

"id": "5c33075129064e76bafbd444c22196de",

"typeName": null,

"type": "02",

"value": "3446448020"

},

{

"id": "7aee444c612d443ca6da8ad30f2288a2",

"typeName": null,

"type": "03",

"value": "9783446448025"

},

{

"id": "f3c464b8d8064402814314e49e4afb2e",

"typeName": "Publishers Order No",

"type": "01",

"value": "553/44802"

}

],

"languages": [

{

"id": "21ad2cac72ef4c5685b010c6dca01e60",

"type": "01",

"value": "ger"

}

],

"prices": [

{

"id": "8ec0d8580832404598e4d2043f12e189",

"type": "04",

"country": "DE",

"territory": null,

"currency": "EUR",

"validFrom": null,

"validUntil": null,

"state": "02",

"taxRate": "R",

"taxRatePercent": 7,

"taxableAmount": 16.81,

"taxAmount": 1.18,

"taxRate2": "S",

"taxRatePercent2": 19,

"taxableAmount2": 1.68,

"taxAmount2": 0.32,

"value": 19.99,

"typeQualifier": null,

"typeDescription": null,

"discountCodeText": null,

"minimumQuantity": null,

"sequence": 2,

"priceTypeGroup": "DUO_BUNDLE",

"fixedRetailPrice": true,

"provisional": false,

"referencePrice": true

},

{

"id": "7b616900c3bc47bfa16dfca3c42ecfbe",

"type": "04",

"country": "AT",

"territory": null,

"currency": "EUR",

"validFrom": null,

"validUntil": null,

"state": "02",

"taxRate": "R",

"taxRatePercent": 10,


"taxAmount": 1.69,

"taxRate2": "S",

"taxRatePercent2": 20,

"taxableAmount2": 1.72,


"taxAmount2": 0.34,

"value": 20.6,

"typeQualifier": null,

"typeDescription": null,

"discountCodeText": null,

"minimumQuantity": null,

"sequence": 1,

"priceTypeGroup": "DUO_BUNDLE",

"fixedRetailPrice": true,

"provisional": false,

"referencePrice": false

}

],

"publishers": [

{

"id": "f6ec0893477941d1a34c8c40f3a3c5b8",

"type": "01",

"name": "Hanser, Carl",

"adbName": "Hanser, Carl, Verlag GmbH & Co. KG",

"nameCodeType": "05",

"publisherId": "5107516",

"imprint": false,

"webSites": [

{

"id": "16d3686e743442f5b7d34387ae9f3ab0",

"type": "01",

"url": "http://www.hanser-fachbuch.de",

"description": null

}

]

}

],

"salesRights": [],

"texts": [

{

"id": "edde83bc5b8c46b5a28103c4cdc82387",

"type": "13",

"formatCode": "06",

"language": "ger",

"value": "Ignatz Schels ist Technik-Informatiker, VBA-Spezialist und zertifizier-

ter Projekt-Fachmann (GPM/IPMA). Er leitet Seminare und Workshops mit Schwerpunkt \"Excel und

Access im Controlling und Projektmanagement\". Sein Spezialgebiet ist die Optimierung von Un-

ternehmensprozessen im ERP- und Microsoft Office-Umfeld. Mit über 50 Fachbüchern, darunter

einige Bestseller, ist er einer der erfolgreichsten IT-Autoren.",

"linkType": null,

"link": null,

"validFrom": null,

"validUntil": null,

"textPublicationDate": null,

"sequence": null

},

{

"id": "f1edccf65db140d38e00b90e48ed5a1b",

"type": "01",

"formatCode": "05",

"language": "ger",

"value": "Excel-Formeln und -Funktionen kennen und beherrschen - über 450 Funktio-

nen, übersichtlich gegliedert in 12 Kategorien<br />Ihr Ratgeber für Excel 2010, 2013 und 2016

beantwortet die wichtigsten Fragen der Tabellenkalkulation: Wie werden Formeln konstruiert und

Funktionen in Formeln eingebaut? Was sind Argumente, wie kommen diese in Funktionen zum Ein-

satz? Nutzen Sie außerdem rund 150 Praxisbeispiele für Ihre tägliche Arbeit.<br /><br />Lernen

Sie die gesamte Funktionsbibliothek kennen und nutzen Sie die volle Excel-Power<br />- Alle

Funktionen aus den einzelnen Kategorien verständlich und anschaulich erklärt<br />- Funktionen

schachteln und kombinieren, Hilfsmittel und Prüftechniken nutzen<br />- Praxisbeispiele zei-

gen, wo und wie Funktionen zum Einsatz kommen<br />- Eigene Funktionen schreiben mit der Mak-

rosprache VBA<br />- Extra: E-Book inside<br /><br />Über 450 Funktionen aus 12 Kategorien

stehen zur Auswahl. Dieses Buch zeigt Ihnen, wie diese abgerufen, konstruiert, verknüpft und

verschachtelt werden. Für den Bezug zur Praxis sorgen die zahlreichen Beispiele, die Sie so-

fort übernehmen können. Lernen Sie auch wichtige Techniken rund um Funktionen kennen, wie dy-

namische Bereichsnamen, Matrixformeln, strukturierte Verweise und vieles mehr.<br /><br />AUS

DEM INHALT //<br />Das Prinzip der Tabellenkalkulation // Rechnen mit Funktionen // Text- und

Logikrechner, statistische Funktionen // Datenbankfunktionen, Tabellen und dynamische Bereiche

// Matrixformeln und -funktionen, logische Funktionen // Formeln aus den Bereichen Mathematik,

Trigonometrie und Finanzmathematik // Technische Funktionen, Cube-Funktionen // Einführung in


die Makrosprache VBA zum Schreiben benutzerdefinierter Funktionen<br /><br

/>Systemvoraussetzungen für E-Book inside: Internet-Verbindung und Adobe-Reader oder Ebook-

Reader bzw. Adobe Digital Editions.",

"linkType": null,

"link": null,

"validFrom": null,

"validUntil": null,

"textPublicationDate": null,

"sequence": null

},

{

"id": "d7ffc1a53d7649c4b5e7c24aab2d4dd6",

"type": "23",

"formatCode": "08",

"language": null,

"value":

"https://api.vlb.de/api/v1/asset/mmo/file/819c535f83f5450a923c4bc40beccef1",

"linkType": "01",

"link": "http://files.hanser.de/Files/Article/ARTK_LPR_9783446448025_0001.pdf",

"validFrom": null,

"validUntil": null,

"textPublicationDate": "07.09.2016",

"sequence": null

}

],

"illustrations": [],

"formFeatures": [],

"wholesalers": [

{

"id": "7286f61961d34fd7bf8533c780c5936b",

"sigl": "C-UAVA",

"orderNumber": null

},

{

"id": "a57aed09485f49eb8389b09286bfe8d7",

"sigl": "C-BZ",

"orderNumber": "19212361"

},

{

"id": "c4218fed46f247bf8e89a460dcf466b5",

"sigl": "U",

"orderNumber": "8874931"

},

{

"id": "ca38300a0dcf4978906f1e3c63432ff9",

"sigl": "VM",

"orderNumber": null

},

{

"id": "818604a98c4f47c5834ee5e8f62ac4c2",

"sigl": "A-HA",

"orderNumber": null

}

],

"mediaFiles": [

{

"id": "a822c7dca8b548d7a7e36396eb2b3602",

"type": "04",

"format": "03",

"linkType": "01",

"value": "https://api.vlb.de/api/v1/cover/9783446448025/m",

"fileDate": null,

"imageResolution": null,

"validFrom": null,

"validUntil": null,

"sequence": null,

"link": "https://api.vlb.de/api/v1/cover/9783446448025/m"

}

],

"webSites": [

{

"id": "28ecf075d37e4f13bff4c46b34dc3a48",

"type": "02",

"url": "http://www.hanser-fachbuch.de/9783446448025",


"description": null

}

],


{

"id": "1aa6945d0af74c86b38ab236395b383a",

"type": "07",

"value": "Bundle"

},

{

"id": "6792114b0158491db4f5b1be500d3042",

"type": "04",

"value": "49019900"

}

],

"collections": [],


{

"id": "c887881f60ad48f490c748034224e1bc",

"type": "27",

"productIdType": "15",

"productIdValue": "9783446450509",

"productForm": "DG",

"productFormDetail": null

},

{

"id": "c1d8f2eb59094b3994f8ec5a840bf901",

"type": "03",

"productIdType": "15",

"productIdValue": "9783446438859",

"productForm": "WW",

"productFormDetail": null

}

],

"containedItems": [

{

"id": "21646218c69540e089f3cd911e131a0b",

"type": "BB",

"productFormDetail": null,

"numberOfPieces": 1,


"productIdentifierType": "03",

"productIdentifierTypeName": null,

"productIdentifierValue": "9783446905368",


"title": "Excel 2016 Formeln und Funktionen",

"sequence": 1,

"country": "DE",

"currency": "EUR",

"value": 17.99,

"taxRate": "R",


"taxAmount": 1.18

},

{

"id": "21646218c69540e089f3cd911e131a0b",

"type": "BB",









"sequence": 1,

"country": "AT",

"currency": "EUR",

"value": 18.54,

"taxRate": "R",


"taxAmount": 1.69

},

{


"id": "2872e91b56624de4bdba0e3a1545e957",

"type": "DG",









"sequence": 2,

"country": "DE",

"currency": "EUR",

"value": 2,

"taxRate": "S",


"taxAmount": 0.32

},

{

"id": "2872e91b56624de4bdba0e3a1545e957",

"type": "DG",









"sequence": 2,

"country": "AT",

"currency": "EUR",

"value": 2.06,

"taxRate": "S",


"taxAmount": 0.34

}

],

"createdDate": "03.12.2015",

"lastModifiedDate": "24.10.2017",

"active": true,

"bitNo": 20949276,

"invoiceStatus": null,

"bundle": true,

"mediumTypeCode": null,

}

5.7. Call a list of product entries

To retrieve several detailed product informations in one call as a list a function has to

be used that needs a list of product IDs (uuid) similar to the stack search.

The order of the uuid’s in the request corresponds to the order of the products in the

result list.

For the stack call a HTTP POST request has to be used where the uuid’s are given in

the payload:

{

"ids": [

“<value>”,

“<value>”,

“<value>”,

…

]

}


5.7.1. Request

URL:


Protocol:

HTTP/S

Authentication necessary:

yes

Request Parameter:

none

5.7.2. Response

HTTP-StatusCode: 200

Format: String

Content:

The following summary list only the most important parameters :

id: The ID of the product to be displayed. The ID is passed in the search

results in the field “id” and can be referenced from there.

version: The version in which a data record is available. This number is incre-

mented each time the record is changed.

composites: The individual blocks (audiences, contributors, etc.) are designated as

composites here. These generally follow ONIX structure and contain

parameters with meaningful names.

There is only one response format - JSON. A response format other than JSON ist

not possible (no JSON-short, no ONIX).

[

product {

...

},

product {

...

},

....

]

5.8. Fetching Media Files

5.8.1. Description



In addition to the cover URLs, the VLB API also offers the URLs for the media files

that belong to a given article. This includes linkage, for example, to back covers, and

inside views.

When multimedia objects, including the cover, are to be fetched, one must ensure

that an access token with appropriate authorization must be used and that it is not

copied or viewed by third parties. For this reason, as a minimum, one must select an

authentication method for which the token cannot be read directly from the media

files URL. The various methods for authentication are stated in section 5.4.2 Authen-

tication. There are also alternative approaches for invoking media files URLs (e.g.

Proxy).

The token for searching and fetching metadata cannot be used to fetch cover or me-

dia files.

The following multimedia objects can be fetched via the VLB API:

Designation JSON Type Media Type File Type

Cover FRONTCOVER image file jpg

Back Cover BACKCOVER image file jpg

Inlay Cover front INLAYCOVER image file jpg

Inside view INSIDE_VIEW image file jpg

Register TABLE_OF_CONTENT PDF file pdf

Annotation ANNOTATION PDF file pdf

Main Description MAIN_DESCRIPTION PDF file pdf

Photo of author AUTHOR_IMAGE image file jpg

Audio sample AUDIO_SAMPLE Audio file mp3 , wave, flac

Video clip VIDEO_CLIP Video file Avi / mpeg / wmv

Review text REVIEW_TEXT PDF file pdf

Review quote REVIEW_QUOTE PDF file pdf

Flap copy FLAP_COPY PDF file pdf

Chapter 1 FIRST_CHAPTER PDF file pdf

Preface INTRODUCTION PDF file pdf

Long description LONG_DESCRIPTION PDF file pdf

Index PRODUCT_INDEX PDF file pdf

Publisher logo PUBLISHER_LOGO image file jpg

Imprint logo IMPRINT_LOGO image file jpg

Author details AUTHOR_DETAILS PDF file pdf

Author interview AUTHOR_INTERVIEW Audio- / Video- / PDF file

mp3 / wave / avi / mpeg / wmv / pdf

Author reading AUTHOR_READING Audio- / Video file

mp3 / wave / avi / mpeg / wmv


5.8.2. Request

URL: http://api.vlb.de/api/v1/asset/mmo/<productId>

Protocol: HTTP/S


Request Parameters

Product ID: The unique identifier of the product for which the media

files URLs are to be fetched

5.8.3. Response


Format: JSON

Content:

type: The type of the media files. Possible types are listed in

chapter 5.8.1

- FRONTCOVER

- BACKCOVER

- see table …

url: The URL under which the media files can be downloaded [

{

"type": "<type>",

"url": "<url>",

“sequenceNumber":"<number>"

}

]

5.8.4. Example

All the media files for a product are to be displayed.

Example for an article with EPUB and frontcover

http://api.vlb.de/api/v1/asset/mmo/192a806ee0bf483da8fad6b7b8ec9308

other media-types:

http://api.vlb.de/api/v1/asset/mmo/518498f30da14eaab8d34364ee2610a8

http://api.vlb.de/api/v1/asset/

http://api.vlb.de/api/v1/asset/mmo/192a806ee0bf483da8fad6b7b8ec9308

http://api.vlb.de/api/v1/asset/mmo/518498f30da14eaab8d34364ee2610a8


Result:

[

{

"type": "INSIDE_VIEW",

"url": "http://test-api.vlb.de/asset/mmo/file/3fcb2d7b-023f-460f-86d6-735b79469451",

"sequenceNumber": 3

},

{


"url": "http://test-api.vlb.de/asset/mmo/file/5d9cd4c4-fedb-4907-be9f-97cf343a861f",

"sequenceNumber": 1

},

{


"url": "http://test-api.vlb.de/asset/mmo/file/5f2ac0ce-f6c7-4091-8e4d-6e9db066a728",

"sequenceNumber": 2

},

{

"type": "FRONTCOVER",

"url": "http://test-api.vlb.de/cover/9783864420184/m",

"sequenceNumber": 1

}

]

5.9. Fetching Covers

5.9.1. Description

The cover link described below can be used to fetch the cover of a title in various

sizes. The cover must be identified by means of the title’s ISBN/GTIN.

Note that the response list of search results presents the cover only in size M.

When fetching cover objects, one must ensure that an access token with appropriate

authorization must be used and that it cannot be copied or viewed from the outside.

Consequently, one must select an authentication method for which the token cannot

be read directly from the cover URL. The various possible authentication methods

are stated in section 5.4.2 Authentication. There are also alternative approaches for

invoking cover URLs (e.g. Proxy).

The token for searching and fetching metadata cannot be used to fetch cover or me-

dia files.

5.9.2. Request

URL: http://api.vlb.de/api/v1/cover/<id>/<size>

Protocol: HTTP/S


Request Parameters

id: The EAN13 of the product for which the cover is to be

fetched

http://api.vlb.de/api/v1/cover/%3cid%3e/%3csize


size: The size of the cover. The values currently possible are:

s small

m medium

l large

no value original size

Size Parameter call

Width Height Commentary

Small s 90 xyz height proportional to width

Medium m 200 xyz height proportional to width

Large l abc 599 width proportional to height

(original size)

abc xyz Original size of cover in VLB

5.9.3. Response


Format: image/jpeg

Content: Cover in binary form

5.10. Index Search

5.10.1. description

Searches can be supported by search indexes for certain fields. When a field index is

invoked for a given search argument, the next 100 entries are found and outputted as

a search results list. Index searches are possible for the following fields:

- Author

- Publisher

- Title

- Keyword

- Collection

- Hierarchy

- Identifier (ISBN / EAN, ÖSB (Austrian School Book) etc. )

There is no paging function for index searches. Consequently, the index search ar-

gument must be changed (relaxed, restricted) if the results list is too short or long.


5.10.2. Request

URL: http://api.vlb.de/api/v1/index/<field>/<search-term>

Protocol: HTTP/S


Request Parameters

field: The field to be searched; can be any of the following:

- Author

- Publisher

- Title

- Keyword

- Set

- Collection

- Identifier (ISBN / EAN)

search-term: the value of interest (to be found by the search)

5.10.3. Response


Format: JSON

Content: Contains a list of all the search results

value: Search result

count: The number of occurrences of this result.

[

{

"value": "<value>",

"count": <value>

}

]

5.10.4. Example

An index search for the author “Meier”:

http://api.vlb.de/api/v1/index/author/meier

Result: [

{

"value": "Meier",

"count": 5

},

{

http://api.vlb.de/api/v1/index/%3cfield%3e/%3csearch-term



http://api.vlb.de/api/v1/index/author/meier


"value": "Meier, Achim",

"count": 2

},

{

"value": "Meier, Adolf",

"count": 1

}

]

5.11. Fetching Publisher Data

5.11.1. Description

This function is used to fetch detailed publisher data. The publisher data are based

on the data of AdB-Online, the address book of the German Booktrade Association.

For access tokens for status independent registrations fetching publisher data is only

possible after activation by MVB customer service.

Publisher data are fetched by means of the Publisher-ID, which is delivered for each

publisher name in a given title.

5.11.2. Request

URL: http://api.vlb.de/api/v1/publisher/<mvbid>

Protocol: HTTP/S


Request Parameters

mvbid: The ID of the publisher for which data is to be fetched

5.11.3. Response


Format: JSON

Content:

This is just a list of the most important response parameters:

mvbId: The MVB ID of the publisher (as in the request parameter)

shortname: The short name for the publisher

name: Name of the publisher written out in full

cityStreet: city matching the street

zipStreet: post code matching the street

http://api.vlb.de/api/v1/publisher/%3cmvbid




location: The name of the place in the publisher’s postal address

country: country of the customer

postbox: Publisher’s post office box

zipPostbox: post code belonging to the post office box

phone: telephone number

fax: fax number

email: email address

url: URL of publisher’s website

isbnPrefix: All ISBN prefixes assigned to this publisher

deliveryBS: delivery information of book wholesaler

deliveryNote SOA delivery note

bagCreditor: true/ false: settlement via the BAG (clearing house for

settlements between book dealers and publishers)

bagDebitor true/ false: settlement via the BAG (clearing house for

settlements between book dealers and publishers)

tax: Publisher’s VAT-ID

siglDe: Sigl Germany

siglAt: Sigl Austria

siglCh: Sigl Schweiz

vnrKreditor: Publisher’s number assigned by the German Book Trade

Association (“Verkehrsnummer”) Germany

vnrKreditorAt: Publisher’s number assigned by the German Book Trade

Association (“Verkehrsnummer”) Austria

vnrKreditorCh: Publisher’s number assigned by the German Book Trade

Association (“Verkehrsnummer”) Switzerland

5.11.4. Example

Fetch of the publisher data for the publisher with ID 5106488:

http://api.vlb.de/api/v1/publisher/5106488

Result: {

"mvbId": "5106488",

"shortName": "MVB",

"name": "MVB Marketing- und Verlagsservice des Buchhandels GmbH",

http://api.vlb.de/api/v1/publisher/510


"cityStreet": "Frankfurt am Main",

"zipStreet": "60311",

"street": "Braubachstr. 16",

"location": "Altstadt",

"country": "D",

"postbox": "10 04 42",

"zipPostbox": "60004",

"phone": "+49 (069) 1306-550",

"fax": "+49 (069) 1306-255",

"email": "[email protected]",

"url": "www.mvb-online.de",

"isbnPrefixes": [

"978-3-7657",

"978-3-655"

],

"deliveryBS": null,

"deliveryNote": null,

"bagCreditor": false,

"bagDebitor": false,

"tax": "DE114130036",

"siglDe": null,

"siglAt": null,

"siglCh": null,

"vnrKreditor": "10871",

"vnrKreditorAt": null,

"vnrKreditorCh": null

}

5.12. Overview of the Aggregators

In the VLB-REST API, data sources are called aggregators. Each title is assigned to

one aggregator.

Aggregator Source ID (to select)

AggregatorID (in Response)

Titles

VLB vlb null All VLB titles without aggrega-tors

ÖSB oesb 5001015 Austrian School Book Data

ALL all One ID per title All possible aggregators combined

Aggregators can be combined with two or more occurrences of the source parameter

(example: ?source=vlb&source=oesb).

6. Examples for queries and api response

The following table contains examples for queries with explanations:

6.1. queries and requests

The following table shows some example queries and requests

Type of requ-est

chapter type request comment


Type of requ-est


quick search 5.5.2

Quick Search

GET search= Carlos%20Ruiz%20Zaf%C3%B3n

quick search for the name „Carlos Ruiz Zaf-ón“

boolean search for a series

5.5.3

Boolean Search

GET search=RH=RC712 search by series ID

boolean search with additional date restriction

5.5.3

Boolean Search

GET se-arch=VL=FISCHER%20Taschenbuch%20und%20AD%3D20140101%5E20150323

Searching for a pub-lisher and rsetriction by change date

stacksearch with additional date restriction

5.5.3

Boolean Search

and Fehler! Verweis-weis-quelle konnte nicht gefun-den werden. 5.5.4

Stack Search

POST search= AD%3D20150319%5E20150320 { "content": [ { "isbn": "9783923*"} , { "isbn": "405000*"} ] }

Stack search for an ISBN range and an additional date re-striction

Boolean keyword search

5.5.3

Boolean Search

GET search=SW=Gl%C3%BCck keyword search

Boolean catch-word search with additional prod-uct-form re-striction

5.5.3

Boolean Search

GET ST=Linux und PF=nicht D* Bzw.: ST=Linux und PF=nicht DG

Catchword search with additional productform restriction (this exam-ple: no digitla products and no ebooks)

Boolean product-type search

5.5.3

Boolean Search

GET search=VL=Langenscheidt und PT= not *Bundle bzw. search=VL=Langenscheidt und PT= *Bundle

Bundle products with taxrate splitting and additional boolean pa-rameter

EAN detailcall 5.6

Fetch-ing Product Entries

GET product/4049817667903/ean detail call for an EAN


Type of requ-est


ISBN Detailaufruf 5.6

Fetch-ing Product Entries

GET product/9783775151061/isbn13 detail call for an ISBN

index request 5.10 In-dex Search

GET index/author/meier request to call the au-thor-index „Meier“

cover request (size „medium“

5.9

Fetch-ing Co-vers

GET https://api.vlb.de/api/v1/cover/9783540537120/m?

For using a cover call a token with additional cover permission is necessary

cover call original size

5.9

Fetch-ing Co-vers

GET https://api.vlb.de/api/v1/cover/9783729608887/?

For using a cover call a token with additional cover permission is necessary

call for all available cover / media ob-jects for this prod-uct

5.8

Fetch-ing Me-dia Files

GET http://api.vlb.de/api/v1/asset/mmo/ec94d0d0471f4e6284f13f1a5f927ce3

To call a list of media objects a token with cover / media permis-sion is necessarry

6.2. API responses

The API response when calling cover or media objects for which special permissions

are necessary is also mentioned in the chapter 5.3.1 Error Codes.

The following tables are not a complete listing of error codes. The API uses the

standard HTTP-error-codes, which are extended by an individual error description.

6.2.1. Response oft he login-function

API-Antwort "error": "unautho-rized"

"error": "unautho-rized"

"error": "un-authorized"

HTTP-Status 401 401 401

Error De-scription

No free slot in one of your regis-tered stateful clients

Bad credentials No stateful client regis-tered for your credentials

All available API slots are in use. Do a logout to free a slot or wait

Wrong login data The user has no right to access the REST-API.


to timeout an unused slot.

Plese request at the custom-er service th API activation.

6.2.2. response for metadata-requsets

These are the responses for a search and request of article details.

Exampl. Call / API response

No data "error": "not_acceptable",

"error": "not_found"

"error": "inva-lid_token"

"error": "unauthor-ized"

"error": "ac-cess_denied"

HTTP-Status 200 406 404 401 401 403

Error De-scription

Could not find ac-ceptable represen-tation

product not found in vlb

Invalid to-ken does not contain resource id (metadata)

api.vlb.de/api/v1/ product/ 9783894410308/isbn13

Not possible

Please set a correct content-type and Accept in the header

Wromng ISBN or invalid iden-tifeier given

Wrong or invalid token

The ac-count / user has no access to archived products

The token / user has no right to access the re-quested data

6.2.3. response for cover- and mediaobject calls

Bsp Aufruf / API response

Keine Daten

T101* "error": "not_ found"

"error": "invalid_ token"


"error": "access_ denied"

"error":

HTTP-Status / Aufruf

HTTP-Status 200 200 404 401 401 403 503

Cover URL Aufruf

api.vlb.de/api/v1/ cov-er/9783770179152/m?

Not possible

Not possib-le

ISBN / identifier not in VLB; no cover available for this article

invalid wrong / token

this account / token has no access to archived articles

Der To-ken / Zu-gang hat keine Berechti-gung das Cover abzurufen

Tempo-rarily there is a problem with the cover accessi-bility – please retry

Medien-daten Links abrufen

api.vlb.de/api/v1/ asset/mmo/ ec94d0d0471f

this article has no media

Not possib-le

wrong iden-tifier

invalid wrong / token

this account / token has no access to media ob-

Der To-ken / Zu-gang hat keine

Tempo-rarily there is a problem


Bsp Aufruf / API response

Keine Daten

T101* "error": "not_ found"

"error": "invalid_ token"


"error": "access_ denied"

"error":

HTTP-Status / Aufruf

HTTP-Status 200 200 404 401 401 403 503

4e6284f13f1a5f927ce3

objects jects ** Berechti-gung die Liste der Medien-objekte abzurufen

with the media objects accessi-bility – please retry

** The account / token can have access rights to covers but no access rights to other

kind of media objects.

7. Encodings

7.1. URL-Encoding

URL parameters must be encoded in URL. Further information about this can be

found under RFC 1738 (http://www.rfc-editor.org/rfc/rfc1738.txt).

7.2. HTML-Encoding

All values in XML format are encoded in HTML.

Further information about encoding characters can be found under

http://www.w3.org/MarkUp/html-spec/html-spec_13.html.

http://www.rfc-editor.org/rfc/rfc1738.txt

http://www.w3.org/MarkUp/html-spec/html-spec_13.html


8. Contact

Technical questions about VLB-REST-API:

MVB

Marketing- und Verlagsservice des Buchhandels GmbH

Braubachstr. 16

60311 Frankfurt am Main, Germany

Postfach 10 04 42

60004 Frankfurt am Main, Germany

Telephone: +49(0) 69 1306-555

E-Mail: [email protected]

General Contact and Service Facility:

MVB Customer Service

Tel. +49 69 1306-555

Fax +49 69 1306-255

[email protected]

mailto:[email protected]

mailto:[email protected]


9. Appendix

9.1. Default Values and Exeptions for Data Fields

- Empty fields will get the value “null”

- Data fields within the “contributor” composite are free text fields.

- The field “identifier” contains the main identifier of the respective product; for

ÖSB-titles the Austrian School Book Number, for books the ISBN without hy-

phens and for non-book-products the GTIN without hyphens.

9.2. Remarks to the Fields in Search Result Lists

The following table contains short explanations for some fields in the search result

list:

Field Name Field Type Values / ONIX Codelist

Example Comment

id Individual value

UUID of the product

identifier Individual value

„identifier“ contains the main identifier of the prod-uct; for ÖSB-titles the Aus-trian Schoolbook Number, for books the ISBN without hyphens and for non-book products the GTIN without hyphens.

isbn Individual value

ISBN with hyphen

issn Individual value

ISSN für magazines

gtin Individual value

Returned for print books, ebooks, audio books and non-books

osbnr Individual value

Austrian Schoolbook Num-ber

bestellnummer Individual value

Order number given by publisher

umbreitNummer Individual value

Order number of wholesal-er Umbreit

cbzNummer Individual value

Order number of „Schwei-zer Buchzentrums“ (SBZ)

edisNummer Individual value

Order number of distributor EDIS

schulbuchBe-stellnummer

Individual value

Ordner number for school-books

title Individual value

Title of the product

subTitle Individual value

Sub title of the product

publisher Individual value

Publisher’s short name in VLB



Example Comment

publisherMvbId Individual value

Publisher’s MVB-ID

publicationDate B003

edition B058 Softcover reprint of the original 1st ed. 1991

availabili-tyStatePublis-her

Original Availability stated by publisher

availabili-tyStateFeed

01 - 04 01 = available 02 = current availability status not known, please contact publisher 03 = temporarily not avail-able 04 = not available

productType Set/series/undefined

priceEurD Individual value

6.95 Euro Price for Germany

priceEurA Individual value

6.95 Euro Price for Austria

priceCHF Individual value

12.5 CHF Price for Switzerland

unpricedItem-Code

null

referencePrice-DE

True / false Flag for reference price in Germany

createDate Individual value

24.03.2015 Creation date of product

lastModified-Date

Individual value

24.03.2015 Last modification date

state active Active or inactive

collections Composite

type Set / series Defines collection or hie-rarchy

title B203 Buch und Buchhandel in Zahlen

Title of collection or hierar-chy

subtitle B029 Zahlen für den Buch-handel

Sub title of collection or hierarchy

identifi-ers

Sub-composite

type elementsub-structure “identifiers”

B273 / Onix Code List 13

04 Collection type

value elementsub-structure “identifiers”

B244 X100426431 / RF084 Identifier of collection or hierarchy

product IdentifierType

elementsub-structure “identifiers”

15 Only filled for collections

type Name

elementsub-structure “identifiers”

B233 VLB-Xnr Only used for hierarchy titles

productFormId Onix Code List 7



Example Comment

contributors Composite

Type Onix Code List 17

first-Name

Individual value

Brigitte First Name

lastNa-me

Individual value

Neuböck-Hubinger Laste Name

group-Name

Individual value

Company name

priceAdditio-nEurD

UVP Labes recommended retail price

taxEurDInfo Individual value

0% VAT given by pub-lisher

VAT given by publisher

taxKeyEurD Individual value

1 VAT key

priceCaEurD Individual value

Ca. approximate price Euro Germany

priceAdditio-nEurA

Individual value

UVP Labels recommended retail price

taxEurAInfo Individual value

0% VAT given by pub-lisher

taxKeyEurA Individual value

1 VAT key

priceCaEurA Individual value

Ca. approximate price Euro Austria

priceAddition-Chf

Individual value

UVP Labels recommended retail price

taxChfInfo Individual value

0% MwSt.-Angabe vom Verlag

taxKeyChf Individual value

1 VAT key

priceCaChf Individual value

Ca. Approximate price CHF

themaSubjects Individual value

WTR Thema subjects

themaQualifiers Individual value

1DFG Thema qualifiers

keyWords Individual value

Onix Code-List 27, value 20

keywords

onSaleDate Individual value

OnSaleDate

Language Onix Code-List 74

eng / ger / fre Language

Sigl C-BZ / A-MLO / U Sigl Information

aggregatorId Null / 5001015 See section 5.12 Overview of the Aggregators

coverUrl Individual value

http://test-api.vlb.de/api/v1/cover/9783142345678/m

Link to cover, if available

shortDescription Individual value

Short description, limited to a maximum of 1.500 char-acters



Example Comment

mainDescription Individual value

Main desctiption, limited to a maximum of 1.500 char-acters

biographicalNo-te

Individual value

Text about the author, lim-ited to a maximum of 1.500 characters

genreCode Individual value

1295 Commodity group number

9.2.1. productType values

The following values can appear in field „productType“

Produktart Produktform b012 / Erläuterung Selektierbar über PT

ProductType (case-sensitive)

Buch B* pbook

E-Book DG ebook

Audio/Video A*, V* abook

Kalender PC calendar

kartographisches Ma-terial

C* map

Digitales Produkt D*, but not DG digital

Non-Book all other values except 00 nonbook

Zeitschrift JO (pseudo code) journal

Undefiniert 00 or no further categroized prod-ucts

undefined

Reihe Series

Hierarchie Set

zweiteiliges Bundle no corresponding ONIX value ja duoBundle

mehrteiliges Bundle no corresponding ONIX value ja multiBundle

Undefiniert no corresponding ONIX value Undefined

9.2.2. taxKeyEurD / taxKeyEurA / taxKeyChf

The following values can appear in field „taxKeyXX“

taxkey Onix Code Bedeutung

0 Z no sales tax

1 R reduced sales tax

2 S full sales tax

6 Bundle products sales tax identification


9.2.3. Genre code – additional Information to „Warengruppen-Klassifikation“ /

genre code classification

The genre code value from the hitlist ist the genre code / Warengruppe of the product.

The same genre code classification is also used in the detailed article data for tag „classification“ for

type “26”.

A detailed overview for the gnre code classification is available (only in german) on the page

www.info.vlb.de – „Verlage“ – „Downloadcenter“

The following list shows the detailed links::

PDF document with annotations: http://info.vlb.de/files/wgsneuversion2_0.pdf

bzw. (Excel-file, only code + translation): http://info.vlb.de/files/wgsneu_mit_index_20060802.xls

http://www.info.vlb.de/

http://info.vlb.de/files/wgsneuversion2_0.pdf

http://info.vlb.de/files/wgsneu_mit_index_20060802.xls


9.3. Overview of the necessary ONIX code lists

9.3.1. Fields without Class Assignment

JSON Field ONIX Code list / values Comment

active Tue / false

id a001

bvdId Null / individual value

aggregatorId See section 5.12 Overview of the Aggre-gators

ID of aggregator for this data set

publicationDate b003 - format DD.MM.YYYY or MM.YYYY or YYYY

announcementDate B086 - format DD.MM.YYYY

availabilityDate J142 - format DD.MM.YYYY

onSaleDate J143 - format DD.MM.YYYY

thesisType B368

thesisPresentedTo B369

thesisYear B370

countryOfManufacture Code list 91 Country of final manu-facture (for customs etc.), according to ONIX list 91, represented in ONIX 2.1 as othertext with typecode 99

availability J396

availabilityStatusCode J141

publishingStatus J292

publishingStatusNote B395 (null)

unpricedItemCode J192 – codelist 57

noContributor N339 (true / false)

phonogramYear B087

Phonogram B047

bisacMainSubject B064

bicMainSubject B065

publicationCity B209

publicationCountry B083

tradeCategory B384

createdDate format DD.MM.YYYY Date when the article was created

lastModifiedDate format DD.MM.YYYY Date of the last change of the article

explicitPublicationDate nio external usage – only VLB internal sys-tem value

bitNo Internal database-identification

bundle True / false Identification as a bun-dle product

9.3.2. audiences

JSON Field ONIX Code list / information Comment

ageFrom Age range start, ONIX field b076 with b075=03



ageTo Age range end, ONIX field b076 with b075=04

codeTypeName Audience code type name (b205) description Audience textual description (b207) rangeCode Audience range code (ONIX field b074)

according to list 30

type Audience code type (ONIX field b204); when "01", then value is from code list 28, equal to b073

value Audience code value (ONIX field b206 or b073, when type = "01")

range True / false Flag telling if the values are defining a range or not

audienceClassification No ONIX equivalent

9.3.3. classifications


code Classification code, ONIX field b069 main Determines whether this is the main

subject/category or not values: true / false (false entspricht “not”)

schemeName SchemeName, ONIX field b171 sourceName Attribute sourceName in [main]subject;

"Enables a data element or composite to carry the name of the source or authority for the data content."

systematicVersion Version number of classification sys-tem, ONIX field b068

type mainsubject, subject or keywords type; ONIX field b067 Code lists 26,27 (which are identical), we are using 27

See chapter 9.2.3 Genre code – additional Infor-mation to „Warengrup-pen-Klassifikation

value [Main]Subject heading, ONIX field b070

9.3.4. collections


levelSequence Structured number ("10.4.3" e.g.) rep-resenting hierarchy of product in set, ONIX field set/b284 or collectionse-quence/x481 in ONIX 3 (no distinction any more between sequence and lev-elSequence!)

Master Reference to the respective collection master record, which contains all in-formation about the collection itself.

Hierarchy- or series head

Identifiers Identifier of the hier-achy- or series head



Sequence Number within series/set/collection; ONIX fields either series/b019, set/b026 or collectionsequence/x481 in ONIX 3

titleInCollection Product title in collection, ONIX field set/b281 or titledetail/titleelement/b203 with titledetail/b202 = "01" (title type code = "Distinctive title") in ONIX 3

9.3.4.1. collections – Subtree master

JSON Feld ONIX Codelist / Info Kommentar

Id

Type Set (Hierarchie) oder series (Reihe)

Title Title of the hierachie or series

abbreviatedTitle

Subtitle Subtitle of the hierachy or series

publisherId

lastModifiedDate Change date of the hierarchy or series

Active True / false

bitNo BitNo of the series / hierachy

concatenateTitle Concatenate title

9.3.4.2. collections - Subtree identifiers (inside Sub master)

JSON Feld ONIX Codelist / Info Kommentar

Id

Typename proprietary value

Type NULL: for X-number of a hierarchy series: 01 oder 04 aus Codelist 13

productIdentifierType Productidentifier type

Value Hierarchy or series identifier

9.3.5. commercialClassifications


type Classification code system, ONIX field b274, according to list 9

value Classification code, ONIX field b275


9.3.6. contributors


biographicalNote Biographical notes, ONIX field b044

dateOfBirth Date of birth, ONIX field b306 with b305=007

dateOfBirthFormat Format of birth date, ONIX field j260, according to list 55, defaulting to YYYYMMDD

dateOfDeath Date of death, ONIX field b306 with b305=008

dateOfDeathFormat Format of death date, ONIX field j260, according to list 55, defaulting to YYYYMMDD

dnbId Identification number of DNB-PND, ONIX field personnameidentifier/b244 (with b390=02)

firstName First name of natural person, ONIX field b039

groupName Name of corporation, ONIX field b047

language source language of translations, ONIX field b252, according to list 74 (ISO 639-2/B)

lastName Last name of natural person, ONIX field b040

professionalAffiliation Professional affiliation, ONIX field b046

professionalPosition Professional affiliation, ONIX field b045

sequence Sequence number, ONIX field b034

sequenceWithinRole Sequence within role, ONIX field b340

type Contribution role according to ONIX code list 17 , ONIX field b035

webSites URLs referring to this contributor; ONIX composite Prod-uct/Contributor/WebSites

fullname

9.3.7. edition


number Edition number, ONIX field b057

release Edition version number, ONIX field b217

text Edition text, ONIX field b058

type Edition type, ONIX field b056, accord-ing to list 21

9.3.8. extent


drm Digital rights management: consolidat-ed information about this product



drmCode Digital rights management information: ONIX code about this product/file, free text field b277 in ONIX 2.1; field x317 filled from list 144 in ONIX 3.0; might be used now also in ONIX 2.1, but not obligatory

duration Duration (of audio work), ONIX field product/extent/b219 with b218=09

Unit: minute

durationUnitCode Deprecated.

epubTypeDescription Free text description of an epublication type (for Ebooks only); ONIX field b213

epubTypeVersion Epublication type version number, ONIX b212

fileFormat File format/type ; ONIX field b211 (for Ebooks only, Abooks use form.detail) filled from code list 10

fileSize File size, ONIX field prod-uct/extent/b219 with b218=22

Unit: bytes

fileSizeUnitCode Deprecated.

illustrationText Free text describing illustrations (and other content like maps etc.), ONIX field product/b062

mapScale The scale of the map (with value xxx meaning 1:xxx), ONIX field prod-uct/b063

numIllustrations Total number of illustrations, ONIX field product/b125

numTracks Number of tracks, ONIX field prod-uct/extent/b219 with b220=11

pages Total (approximate) number of pages, ONIX field product/b061

pagesArabic Number of pages in arabic numerals, ONIX field product/b255

pagesRoman Number of pages in roman numerals, ONIX field product/b254

The filesize (fileSize) is normalized on bytes (List 24 Code 17).

The duration (duration) is normalized on minutes (List 24 Code 05).

9.3.9. form


binding NON-ONIX field; BvD-VLB specific (@see OnixCodeList_21_03_BVD-1.xslx/BvdCodes; ProductBinding (List 216, defined as pseudo code list).

description ONIX field b014

detail ONIX field b333

diameter ONIX field c094 with c093=09 or 12, unit is mm (c095=mm)

height ONIX field c094 with c093=01, unit is mm (c095=mm)

numberOfPieces Number of pieces contained (ONIX field b210)

packaging ONIX field b225, Onix code list 80



productContentType product content type, ONIX field , code list 81; optional, repeatable

thickness ONIX field c094 with c093=03, unit is mm

type ONIX field b012

weight ONIX field c094 with c093=08, unit is gramm (c095=gr)

width ONIX field c094 with c093=02, unit is mm (c095=mm)

9.3.10. formFeature


code Form feature code, ONIX field b335, according to lists 76, 98, 99, 143, 176, 184 or 196, depending on code value (Great!

description Form feature description, ONIX field b336

type Form feature type code, ONIX field b334, according to list 79

9.3.11. identifier


type Product identifier type code, ONIX field b221, according to list 5

value Product identifier value, ONIX field b244

9.3.12. illustration


description Illustration textual description, ONIX field b361

number Illustration count for the given type, ONIX field b257

type Illustration type code, ONIX field b256, according to list 25

9.3.13. languages


type ONIX field b253

value ONIX field b252

9.3.14. mediaFiles


fileDate last date of file change, ONIX field f373

format Asset format code, ONIX field f115, according to list 39

imageResolution image resolution as dpi, ONIX field f259

internalUrl For internal use by the asset store.



linkType Link type code, ONIX field f116, ac-cording to list 40

type Asset type code, ONIX field f114, ac-cording to list 38

validFrom For internal use by the asset store.

validUntil For internal use by the asset store.

value The link itself as delivered by the pub-lisher, ONIX field f117

9.3.15. prices


country Price country code, ONIX field b251, according to list 91 (ISO 3166-1, 2-letter)

currency Price currency code, ONIX field j152, according to list 96 (ISO 4217)

discountCodeText Discount description; content of j364, where j363 == "02" and textformat == "06"; special extension for SBZ prod-ucts

fixedRetailPrice true / false (J148=04 = true) no ONIX field, fixed retail price

minimumQuantity Minimum quantity to order for the given price, ONIX field j263

priceTypeGroup

provisional True / false no ONIX field, flag for approximate price

referencePrice true / false no ONIX field, flag for reference price from VLB

sequence

state Price state code, ONIX field j266, ac-cording to list 61

taxRate Tax rate code, ONIX field j153, accord-ing to list 62

Important: This code is used in NON-bundle-products fort he product itself Bundle-products: taxrate-code for bundle-part-product 1

taxRatePercent Taxrate in percentage terms – bundle-part-product 1*

taxableAmount Netto value – bundle-part-product 1*

taxAmount Amount of a tax – bun-dle-part-product 1*

taxRate2 taxrate-code for bundle-part-product 2* (only Duo-bundle-products)



taxRatePercent2 Taxrate in percentage terms – bundle-part-product 2* (only Duo-bundle-products)

taxableAmount2 Netto value – bundle-part-product 2* (only Duo-bundle-products)

taxAmount Amount of a tax – bun-dle-part-product 2* (only Duo-bundle-products)

territory Price territory code, ONIX field j303, according to list 49

type Price type code, ONIX field j148, ac-cording to list 58.

typeDescription Price type description, ONIX field j262

typeQualifier Price type qualifier, ONIX field j261, according to list 59

validFrom Price validity start, ONIX field j161

validUntil Price validity end, ONIX field j162

value The price value, ONIX field j151 Gross-all-in price (for the complete bundle-product)

* newly added

9.3.16. publisher


adbName Official publisher name, taken from "ADB-Ansetzung"

imprint If true, denotes that publisher infor-mation has been imported from an imprint composite; if false, it was a publisher composite

name Publisher name, ONIX field b081, mapped to "VLB-Kurzbezeichnung"

nameCodeType Name Code Type, ONIX field b241, according to List 44

publisherId Publisher identifier, ONIX field b243 with b241=nameCodeType; normal-ized to type Name-Code.GERMAN_ISBN_PUB_ID (MVB-ID)

type Publisher role type code, ONIX field b291, according to list 45

webSites URLs referring to this publisher; ONIX composite Product/Publisher/WebSites

9.3.17. relatedProducts


productForm Product form of the related product, ONIX field b012, according to list 7



productFormDetail Product form detail of the related prod-uct, ONIX field b333, according to list 78

productIdType Identifier type of the related product; ONIX field productidentifier/b221

productIdValue Identifier of the related product; ONIX field productidentifier/b244

type Type of relation, ONIX field h208, ac-cording to list 51

9.3.18. salesRight


country country of validity for this sales right, ONIX field b090, according to list 91 (ISO 3166-1, 2 letter code)

region Deprecated.

territory territory of validity for this sales right, ONIX field b388, according to list 49 (UN LOCODE)

type Typecode of sales right, ONIX field b089, according to list 46

9.3.19. texts


assetFileId For internal use by the asset store.

formatCode Text format, ONIX field d103 or attrib-ute "textformat" in tag d104/Text, ac-cording to list 34

internalUrl For internal use by the asset store.

language Text language, give as attribute "lan-guage" in tag d104/Text, according to list 74

link ONIX field d106

linkType ONIX field d105

textPublicationDate ONIX field b109

type Text type/purpose, ONIX field d102, according to list 33

validFrom ONIX field b324

validUntil ONIX field b325

value The text itself, ONIX field d104

9.3.20. titles


subtitle ONIX field b029

title ONIX field b203

type title type; ONIX field b202

9.3.21. websites




type ONIX field b367, ONIX Codelist / Info 73

url ONIX field b295

Description ONIX field b294

9.3.22. wholesalers


orderNumber - Order Number

sigl - Sigl label

9.3.23. publisherData

For access tokens for status independent registrations the composite “publisherData”

is only available after activation by the MVB customer service.

JSON Field Example Comment

mvbId 5106488

shortName MVB

name MVB Marketing- und Verlagsservice des Buchhandels GmbH

street Braubachstr. 16

location Altstadt

country D

postbox 10 04 42

phone +49 (069) 1306-550

fax +49 (069) 1306-255

email [email protected]

url www.mvb-online.de

identificationNo 204

isbnPrefixes 978-3-7657,978-3-65

deliveryBS null

deliveryNote „“

bagCreditor false

bagDebitor false

tax DE114130036 value added tax identifi-cation number

siglDe German distributor seal

siglAt Austrian distributor seal

siglCh Swiss distributor seal

vnrKreditor 10871 Publisher’s number as-signed by the German Book Trade Association (“Verkehrsnummer”)

vnrKreditorAt Austrian book trade identification number

vnrKreditorCh Swiss book trade identi-fication number

9.3.24. containeditems


JSON Field Example Comment

type Onix field b012 productform

productFormDetail b333, according to list 78

numberOfPieces Can be 1 or hihger

productContentType Onix Feld b385 – List 81

productIdentifierType (Teilbereich von b221), according to list 5

Productidentifier type * • 01 = Proprietär • 03 = GTIN-13

productIdentifierTypeNa-me

Onix Feld b233

productIdentifierValue B244 Identifier (proprietary or GTIN-13)*

description Onix Feld b014

sequence VLB internal sequence number

country Onix field b251 – List 91 country (differentiating between DE / german and AT / austrian bundle for bundle products)

currency currency

value akutell gültiger Brutto-Preis des Teil-produktes innerhalb des Bundles

taxRate (Onix Feld j157) taxrate.* • Z = none • R = reduced • S = full

taxableAmount Onix Feld j155

taxAmount Onix Feld j156

title Title oft he bundle prod-uct part

taxInfo VLB internal info

9.3.25. look-up-table for the detailview Detailansicht

9.3.25.1. audiences – audienceClassification

field content description comment

main_description main description customer_group customer group reading_age Lesealter fsk FSK

Please regard the values in the „type“ definition oft he corresponding object.

9.3.25.2. classifications – schemeName

These values have no corresponding ONIX setting. (b171 - Proprietary subject

scheme name).

These values can be changed at any time. Please regard the values in the „type“ def-

inition oft he corresponding object.


9.3.25.3. classifications – sourceName

The attribut sourceName identifies in the (main)subject the source of the classifica-

tion.

These values can be changed at any time and have no corresponding ONIX setting.


9.3.25.4. prices - priceTypeGroup

Values for the VLB internally used prices classification (VLB-intern).

These values can be changed at any time and have no corresponding ONIX setting.


VLB REST API Specificationsinfo.vlb.de/media/vlb_rest_api_userspecification.pdfVLB REST API...

Documents

Transcript of VLB REST API Specificationsinfo.vlb.de/media/vlb_rest_api_userspecification.pdfVLB REST API...