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
VLB REST API Specifications 2 / 79
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
VLB REST API Specifications 3 / 79
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
VLB REST API Specifications 4 / 79
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
VLB REST API Specifications 5 / 79
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.
VLB REST API Specifications 6 / 79
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
VLB REST API Specifications 7 / 79
- 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
VLB REST API Specifications 8 / 79
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.
VLB REST API Specifications 9 / 79
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)
VLB REST API Specifications 10 / 79
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>
VLB REST API Specifications 11 / 79
The live environment should be used for the development phase as well as for the
productive usage at the customer.
VLB REST API Specifications 12 / 79
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>"
VLB REST API Specifications 13 / 79
}
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.
VLB REST API Specifications 14 / 79
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.
VLB REST API Specifications 15 / 79
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:
HTTP StatusCode: 200
Format: None
Content: No
VLB REST API Specifications 16 / 79
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
VLB REST API Specifications 17 / 79
- 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
VLB REST API Specifications 18 / 79
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
VLB REST API Specifications 19 / 79
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).
VLB REST API Specifications 20 / 79
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
VLB REST API Specifications 21 / 79
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
VLB REST API Specifications 22 / 79
- 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
HTTP StatusCode: 200
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
VLB REST API Specifications 23 / 79
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>",
VLB REST API Specifications 24 / 79
"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>
}
VLB REST API Specifications 25 / 79
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"
],
VLB REST API Specifications 26 / 79
"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
VLB REST API Specifications 27 / 79
HTTP StatusCode: 200
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>,
"publicationDate": <value>,
"announcementDate": <value>,
"availabilityDate": <value>,
"onSaleDate": <value>,
"titles": [
{
"id": <value>,
"type": <value>,
"subtitle": <value>,
"title": "<value>"
}
],
"thesisType": <value>,
"thesisPresentedTo": <value>,
"thesisYear": <value>,
VLB REST API Specifications 28 / 79
"countryOfManufacture": <value>,
"availability": <value>,
"availabilityStatusCode": <value>,
"publishingStatus": <value>,
"unpricedItemCode": <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>,
"fileFormat": <value>,
"epubTypeDescription": <value>,
"drm": "<value>"
},
"audiences": [
{
"id": <value>,
"type": <value>,
"value": <value>,
"rangeCode": <value>,
"ageFrom": <value>,
"ageTo": <value>,
"description": <value>,
"codeTypeName": <value>,
"range": <value>
}
],
"contributors": [
{
"id": <value>,
"sequence": <value>,
"type": <value>,
"sequenceWithinRole": <value>,
"firstName": <value>,
"lastName": <value>,
"groupName": <value>,
VLB REST API Specifications 29 / 79
"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>"
}
],
VLB REST API Specifications 30 / 79
"texts": [
{
"id": <value>,
"type": <value>,
"formatCode": <value>,
"language": <value>,
"value": <value>,
"linkType": <value>,
"link": <value>,
"validFrom": <value>,
"validUntil": <value>,
"assetFileId": <value>,
"internalUrl": <value>,
"externallyGenerated": <value>
}
],
"illustrations": [
{
"id": <value>,
"type": <value>,
"description": <value>,
"number": <value>
},
{
"id": <value>,
"type": <value>,
"description": <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>,
"lastModifiedDate": <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)
VLB REST API Specifications 31 / 79
{
{
"id": <value>,
"notificationType": <value>,
"bvdId": <value>,
"aggregatorId": <value>,
"providerId": <value>,
"publicationDate": <value>,
"announcementDate": <value>,
"availabilityDate": <value>,
"onSaleDate": <value>,
"titles": [
{
"id": <value>,
"type": <value>,
"subtitle": <value>,
"title": <value>
},
{
"id": <value>,
"type": <value>,
"subtitle": <value>,
"title": <value>
}
],
"thesisType": <value>,
"thesisPresentedTo": <value>,
"thesisYear": <value>,
"countryOfManufacture": <value>,
"availability": <value>,
"availabilityStatusCode": <value>,
"publishingStatus": <value>,
"publishingStatusNote": <value>,
"unpricedItemCode": <value>,
"noContributor": <value>,
"phonogramYear": <value>,
"phonogram": <value>,
"bisacMainSubject": <value>,
"bicMainSubject": <value>,
"publicationCity": [
<value>
],
"publicationCountry": <value>,
"tradeCategory": <value>,
"edition": {
"id": <value>,
"type": <value>,
"number": <value>,
"text": <value>,
"release": <value>
},
"form": {
"id": <value>,
"type": <value>,
"binding": <value>,
"description": <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>,
VLB REST API Specifications 32 / 79
"numTracks": <value>,
"illustrationText": <value>,
"pages": <value>,
"pagesRoman": <value>,
"pagesArabic": <value>,
"fileFormat": <value>,
"epubTypeDescription": <value>,
"drm": <value>,
"drmCode": <value>,
"epubTypeVersion": <value>
},
"zisInfo": <value>,
"audiences": [
{
"id": <value>,
"type": <value>,
"value": <value>,
"rangeCode": <value>,
"ageFrom": <value>,
"ageTo": <value>,
"description": <value>,
"codeTypeName": <value>,
"audienceClassification": "customer_group",
"range": <value>
},
{
"id": <value>,
"type": <value>,
"value": <value>,
"rangeCode": <value>,
"ageFrom": <value>,
"ageTo": <value>,
"description": <value>,
"codeTypeName": <value>,
"audienceClassification": "main_description",
"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>,
"webSites": [
{
"id": <value>,
"type": <value>,
"url": <value>,
"description": <value>
}
],
"company": <value>,
"fullName": <value>,
"value": <value>
}
],
"classifications": [
{
"id": <value>,
"type": <value>,
"systematicVersion": <value>,
VLB REST API Specifications 33 / 79
"code": <value>,
"value": <value>,
"schemeName": <value>,
"sourceName": <value>,
"main": <value>
},
{
"id": <value>,
"type": <value>,
"systematicVersion": <value>,
"code": <value>,
"value": <value>,
"schemeName": <value>,
"sourceName": <value>,
"main": <value>
},
{
"id": <value>,
"type": <value>,
"systematicVersion": <value>,
"code": <value>,
"value": <value>,
"schemeName": <value>,
"sourceName": <value>,
"main": <value>
},
{
"id": <value>,
"type": <value>,
"systematicVersion": <value>,
"code": <value>,
"value": <value>,
"schemeName": <value>,
"sourceName": <value>,
"main": <value>
},
],
"identifiers": [
{
"id": <value>,
"typeName": <value>,
"type": <value>,
"value": <value>
},
{
"id": <value>,
"typeName": <value>,
"type": <value>,
"value": <value>
},
{
"id": <value>,
"typeName": <value>,
"type": <value>,
"value": <value>
}
],
"languages": [
{
"id": <value>,
"type": <value>,
"value": <value>
}
],
"prices": [
{
"id": <value>,
"type": <value>,
"country": <value>,
"territory": <value>,
"currency": <value>,
"validFrom": <value>,
"validUntil": <value>,
"state": <value>,
VLB REST API Specifications 34 / 79
"taxRate": <value>,
"taxRatePercent": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"taxRate2": <value>,
"taxRatePercent2": <value>,
"taxableAmount2": <value>,
"taxAmount2": <value>,
"value": <value>,
"typeQualifier": <value>,
"typeDescription": <value>,
"discountCodeText": <value>,
"minimumQuantity": <value>,
"sequence": <value>,
"priceTypeGroup": <value>,
"fixedRetailPrice": <value>,
"provisional": <value>,
"referencePrice": <value>
},
{
"id": <value>,
"type": <value>,
"country": <value>,
"territory": <value>,
"currency": <value>,
"validFrom": <value>,
"validUntil": <value>,
"state": <value>,
"taxRate": <value>,
"taxRatePercent": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"taxRate2": <value>,
"taxRatePercent2": <value>,
"taxableAmount2": <value>,
"taxAmount2": <value>,
"value": <value>,
"typeQualifier": <value>,
"typeDescription": <value>,
"discountCodeText": <value>,
"minimumQuantity": <value>,
"sequence": <value>,
"priceTypeGroup": <value>,
"fixedRetailPrice": <value>,
"provisional": <value>,
"referencePrice": <value>
},
{
"id": <value>,
"type": <value>,
"country": <value>,
"territory": <value>,
"currency": <value>,
"validFrom": <value>,
"validUntil": <value>,
"state": <value>,
"taxRate": <value>,
"taxRatePercent": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"taxRate2": <value>,
"taxRatePercent2": <value>,
"taxableAmount2": <value>,
"taxAmount2": <value>,
"value": <value>,
"typeQualifier": <value>,
"typeDescription": <value>,
"discountCodeText": <value>,
"minimumQuantity": <value>,
"sequence": <value>,
"priceTypeGroup": <value>,
"fixedRetailPrice": <value>,
"provisional": <value>,
"referencePrice": <value>
VLB REST API Specifications 35 / 79
},
{
"id": <value>,
"type": <value>,
"country": <value>,
"territory": <value>,
"currency": <value>,
"validFrom": <value>,
"validUntil": <value>,
"state": <value>,
"taxRate": <value>,
"taxRatePercent": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"taxRate2": <value>,
"taxRatePercent2": <value>,
"taxableAmount2": <value>,
"taxAmount2": <value>,
"value": <value>,
"typeQualifier": <value>,
"typeDescription": <value>,
"discountCodeText": <value>,
"minimumQuantity": <value>,
"sequence": <value>,
"priceTypeGroup": <value>,
"fixedRetailPrice": <value>,
"provisional": <value>,
"referencePrice": <value>
},
{
"id": <value>,
"type": <value>,
"country": <value>,
"territory": <value>,
"currency": <value>,
"validFrom": <value>,
"validUntil": <value>,
"state": <value>,
"taxRate": <value>,
"taxRatePercent": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"taxRate2": <value>,
"taxRatePercent2": <value>,
"taxableAmount2": <value>,
"taxAmount2": <value>,
"value": <value>,
"typeQualifier": <value>,
"typeDescription": <value>,
"discountCodeText": <value>,
"minimumQuantity": <value>,
"sequence": <value>,
"priceTypeGroup": <value>,
"fixedRetailPrice": <value>,
"provisional": <value>,
"referencePrice": <value>
}
],
"publishers": [
{
"id": <value>,
"type": <value>,
"name": <value>,
"adbName": <value>",
"nameCodeType": <value>,
"publisherId": <value>,
"imprint": <value>,
"webSites": []
}
],
"salesRights": [
{
"id": <value>,
"type": <value>,
VLB REST API Specifications 36 / 79
"country": <value>,
"region": <value>,
"territory": <value>
}
],
"texts": [
{
"id": <value>,
"type": <value>,
"formatCode": <value>,
"language": <value>,
"value": <value>,
"linkType": <value>,
"link": <value>,
"validFrom": <value>,
"validUntil": <value>,
"textPublicationDate": <value>
},
{
"id": <value>,
"type": <value>,
"formatCode": <value>,
"language": <value>,
"value": <value>,
"linkType": <value>,
"link": <value>,
"validFrom": <value>,
"validUntil": <value>,
"textPublicationDate": <value>
},
{
"id": <value>,
"type": <value>,
"formatCode": <value>,
"language": <value>,
"value": <value>,
"linkType": <value>,
"link": <value>,
"validFrom": <value>,
"validUntil": <value>,
"textPublicationDate": <value>
},
{
"id": <value>,
"type": <value>,
"formatCode": <value>,
"language": <value>,
"value": <value>,
"linkType": <value>,
"link": <value>,
"validFrom": <value>,
"validUntil": <value>,
"textPublicationDate": <value>
},
{
"id": <value>,
"type": <value>,
"formatCode": <value>,
"language": <value>,
"value": <value>",
"linkType": <value>,
"link": <value>,
"validFrom": <value>,
"validUntil": <value>,
"textPublicationDate": <value>
}
],
"illustrations": [
{
"id": <value>,
"type": <value>,
"description": <value>,
"number": <value>
}
VLB REST API Specifications 37 / 79
],
"formFeatures": [
{
"id": <value>,
"type": <value>,
"code": <value>,
"description": <value>,
"value": <value>
}
],
"wholesalers": [
{
"id": <value>,
"sigl": <value>,
"orderNumber": <value>
},
{
"id": <value>,
"sigl": <value>,
"orderNumber": <value>
},
{
"id": <value>,
"sigl": <value>,
"orderNumber": <value>
},
{
"id": <value>,
"sigl": <value>,
"orderNumber": <value>
},
{
"id": <value>,
"sigl": <value>,
"orderNumber": <value>
}
],
"mediaFiles": [
{
"id": <value>,
"type": <value>,
"format": <value>,
"linkType": <value>,
"value": <value>,
"fileDate": <value>,
"imageResolution": <value>,
"validFrom": <value>,
"validUntil": <value>,
"link": <value>
},
{
"id": <value>,
"type": <value>,
"format": <value>,
"linkType": <value>,
"value": <value>,
"fileDate": <value>,
"imageResolution": <value>,
"validFrom": <value>,
"validUntil": <value>,
"link": <value>
}
],
"webSites": [
{
"id": <value>,
"type": <value>,
"url": <value>,
"description": <value>
}
],
"commercialClassifications": [
{
"id": <value>,
VLB REST API Specifications 38 / 79
"type": <value>,
"value": <value>
}
],
"collections": [
{
"id": <value>,
"master": {
"id": <value>,
"type": "series",
"identifiers": [
{
"id": <value>,
"typeName": <value>,
"type": <value>,
"productIdentifierType": <value>,
"value": <value>
}
],
"title": <value>,
"abbreviatedTitle": <value>,
"subtitle": <value>,
"publisherId": <value>,
"lastModifiedDate": <value>,
"active": <value>,
"bitNo": <value>,
"deletionDate": <value>,
"concatenateTitle": <value>
},
"sequence": <value>,
"levelSequence": <value>,
"titleInCollection": <value>
}
],
"relatedProducts": [
{
"id": <value>,
"type": <value>,
"productIdType": <value>,
"productIdValue": <value>,
"productForm": <value>,
"productFormDetail": <value>
}
],
"containedItems": [
{
"id": <value>,
"type": <value>,
"productFormDetail": <value>,
"numberOfPieces": <value>,
"productContentType": <value>,
"productIdentifierType": <value>,
"productIdentifierTypeName": <value>,
"productIdentifierValue": <value>,
"description": <value>,
"sequence": <value>,
"country": <value>,
"currency": <value>,
"value": <value>,
"taxRate": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"title": <value>,
"taxInfo": <value>
},
{
"id": <value>,
"type": <value>,
"productFormDetail": <value>,
"numberOfPieces": <value>,
"productContentType": <value>,
"productIdentifierType": <value>,
"productIdentifierTypeName": <value>,
"productIdentifierValue": <value>,
VLB REST API Specifications 39 / 79
"description": <value>,
"sequence": <value>,
"country": <value>,
"currency": <value>,
"value": <value>,
"taxRate": <value>,
"taxableAmount": <value>,
"taxAmount": <value>,
"title": <value>,
"taxInfo": <value>
}
],
"priceRepealDate": null,
"notPriceRefRelevantDate": <value>,
"priceDataDachChangeDate": <value>,
"priceDataInternationalChangeDate": <value>,
"createdDate": <value>,
"lastModifiedDate": <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">
VLB REST API Specifications 40 / 79
<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,
"publicationCity": [
"München"
],
"publicationCountry": "DE",
"tradeCategory": null,
"edition": {
VLB REST API Specifications 41 / 79
"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"
}
],
"classifications": [
{
"id": "18d81df419034fefbb400554245693ed",
"type": "18",
"systematicVersion": null,
"code": "004",
"value": "Informatik",
"schemeName": null,
VLB REST API Specifications 42 / 79
"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",
"systematicVersion": "1.1",
"code": "UFC",
"value": "Tabellenkalkulation",
"schemeName": "MainSubject",
"sourceName": "Publisher",
"main": true
},
{
"id": "7704a580f54d459896e0c624753cd5af",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Excel",
"schemeName": null,
"sourceName": null,
"main": false
},
{
"id": "ae381fec3dbf45f6b75661a7395c81b6",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Formeln",
"schemeName": null,
"sourceName": null,
"main": false
},
{
"id": "91c344d4c7db419ca2d5723dfc7d36ae",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Funktionen",
"schemeName": null,
"sourceName": null,
"main": false
},
{
"id": "8dc331117c674edc85fe0465b414bd57",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Office",
"schemeName": null,
"sourceName": null,
"main": false
},
{
"id": "c3eae6dbbe5a4dc7899014efa0b713d1",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Pivot",
"schemeName": null,
"sourceName": null,
"main": false
},
{
VLB REST API Specifications 43 / 79
"id": "cf9d78a80f524f3bb83f3a1c59a9a326",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Tabellen",
"schemeName": null,
"sourceName": null,
"main": false
},
{
"id": "ce2ec0792c7949eb95388c2cedf4aa45",
"type": "20",
"systematicVersion": null,
"code": null,
"value": "Tabellenkalkulation",
"schemeName": null,
"sourceName": null,
"main": false
},
{
"id": "d7361a5854c24fa6bfd4ecab0bc87c49",
"type": "23",
"systematicVersion": null,
"code": "FBITANWE",
"value": "Anwendersoftware",
"schemeName": "FBSysNeu",
"sourceName": null,
"main": false
},
{
"id": "ffdd3f2a36fb498c8e6a9272ca6f95ad",
"type": "23",
"systematicVersion": null,
"code": "INF2016",
"value": null,
"schemeName": "Hanser eLibrary Pakete",
"sourceName": null,
"main": false
},
{
"id": "bee38238bba8464cb929aab48dc69646",
"type": "24",
"systematicVersion": null,
"code": "00100",
"value": null,
"schemeName": "Artikeltyp",
"sourceName": null,
"main": false
},
{
"id": "c51fd06cdd22413e82fdd5f1c5084cfa",
"type": "24",
"systematicVersion": "2.0",
"code": "25530",
"value": null,
"schemeName": "Produktgruppe",
"sourceName": null,
"main": false
},
{
"id": "20e4cf3717d542dcb35e025a1384fdd5",
"type": "24",
"systematicVersion": null,
"code": "55300",
"value": null,
"schemeName": "Verlagssektor",
"sourceName": null,
"main": false
}
],
"identifiers": [
{
"id": "25b19e906e1e40f69f1b30448f82bfe9",
"typeName": null,
VLB REST API Specifications 44 / 79
"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,
"taxableAmount": 16.85,
"taxAmount": 1.69,
"taxRate2": "S",
"taxRatePercent2": 20,
"taxableAmount2": 1.72,
VLB REST API Specifications 45 / 79
"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
VLB REST API Specifications 46 / 79
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",
VLB REST API Specifications 47 / 79
"description": null
}
],
"commercialClassifications": [
{
"id": "1aa6945d0af74c86b38ab236395b383a",
"type": "07",
"value": "Bundle"
},
{
"id": "6792114b0158491db4f5b1be500d3042",
"type": "04",
"value": "49019900"
}
],
"collections": [],
"relatedProducts": [
{
"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,
"productContentType": null,
"productIdentifierType": "03",
"productIdentifierTypeName": null,
"productIdentifierValue": "9783446905368",
"description": null,
"title": "Excel 2016 Formeln und Funktionen",
"sequence": 1,
"country": "DE",
"currency": "EUR",
"value": 17.99,
"taxRate": "R",
"taxableAmount": 16.81,
"taxAmount": 1.18
},
{
"id": "21646218c69540e089f3cd911e131a0b",
"type": "BB",
"productFormDetail": null,
"numberOfPieces": 1,
"productContentType": null,
"productIdentifierType": "03",
"productIdentifierTypeName": null,
"productIdentifierValue": "9783446905368",
"description": null,
"title": "Excel 2016 Formeln und Funktionen",
"sequence": 1,
"country": "AT",
"currency": "EUR",
"value": 18.54,
"taxRate": "R",
"taxableAmount": 16.85,
"taxAmount": 1.69
},
{
VLB REST API Specifications 48 / 79
"id": "2872e91b56624de4bdba0e3a1545e957",
"type": "DG",
"productFormDetail": null,
"numberOfPieces": 1,
"productContentType": null,
"productIdentifierType": "03",
"productIdentifierTypeName": null,
"productIdentifierValue": "9783446905375",
"description": null,
"title": "Excel 2016 Formeln und Funktionen",
"sequence": 2,
"country": "DE",
"currency": "EUR",
"value": 2,
"taxRate": "S",
"taxableAmount": 1.68,
"taxAmount": 0.32
},
{
"id": "2872e91b56624de4bdba0e3a1545e957",
"type": "DG",
"productFormDetail": null,
"numberOfPieces": 1,
"productContentType": null,
"productIdentifierType": "03",
"productIdentifierTypeName": null,
"productIdentifierValue": "9783446905375",
"description": null,
"title": "Excel 2016 Formeln und Funktionen",
"sequence": 2,
"country": "AT",
"currency": "EUR",
"value": 2.06,
"taxRate": "S",
"taxableAmount": 1.72,
"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>”,
…
]
}
VLB REST API Specifications 49 / 79
5.7.1. Request
URL:
http://api.vlb.de/api/v1/product/multipleProducts
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
VLB REST API Specifications 50 / 79
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
VLB REST API Specifications 51 / 79
5.8.2. Request
URL: http://api.vlb.de/api/v1/asset/mmo/<productId>
Protocol: HTTP/S
Authentication: required
Request Parameters
Product ID: The unique identifier of the product for which the media
files URLs are to be fetched
5.8.3. Response
HTTP StatusCode: 200
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
VLB REST API Specifications 52 / 79
Result:
[
{
"type": "INSIDE_VIEW",
"url": "http://test-api.vlb.de/asset/mmo/file/3fcb2d7b-023f-460f-86d6-735b79469451",
"sequenceNumber": 3
},
{
"type": "INSIDE_VIEW",
"url": "http://test-api.vlb.de/asset/mmo/file/5d9cd4c4-fedb-4907-be9f-97cf343a861f",
"sequenceNumber": 1
},
{
"type": "INSIDE_VIEW",
"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
Authentication: required
Request Parameters
id: The EAN13 of the product for which the cover is to be
fetched
VLB REST API Specifications 53 / 79
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
HTTP StatusCode: 200
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.
VLB REST API Specifications 54 / 79
5.10.2. Request
URL: http://api.vlb.de/api/v1/index/<field>/<search-term>
Protocol: HTTP/S
Authentication: required
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
HTTP StatusCode: 200
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
},
{
VLB REST API Specifications 55 / 79
"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
Authentication: required
Request Parameters
mvbid: The ID of the publisher for which data is to be fetched
5.11.3. Response
HTTP StatusCode: 200
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
VLB REST API Specifications 56 / 79
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",
VLB REST API Specifications 57 / 79
"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
VLB REST API Specifications 58 / 79
Type of requ-est
chapter type request comment
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
VLB REST API Specifications 59 / 79
Type of requ-est
chapter type request comment
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.
VLB REST API Specifications 60 / 79
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": "unauthor-ized"
"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
VLB REST API Specifications 61 / 79
Bsp Aufruf / API response
Keine Daten
T101* "error": "not_ found"
"error": "invalid_ token"
"error": "unauthor-ized"
"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.
VLB REST API Specifications 62 / 79
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
VLB REST API Specifications 63 / 79
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
VLB REST API Specifications 64 / 79
Field Name Field Type Values / ONIX Codelist
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
VLB REST API Specifications 65 / 79
Field Name Field Type Values / ONIX Codelist
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
VLB REST API Specifications 66 / 79
Field Name Field Type Values / ONIX Codelist
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
VLB REST API Specifications 67 / 79
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
VLB REST API Specifications 68 / 79
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
VLB REST API Specifications 69 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
VLB REST API Specifications 70 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
type Classification code system, ONIX field b274, according to list 9
value Classification code, ONIX field b275
VLB REST API Specifications 71 / 79
9.3.6. contributors
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
drm Digital rights management: consolidat-ed information about this product
VLB REST API Specifications 72 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
VLB REST API Specifications 73 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
type Product identifier type code, ONIX field b221, according to list 5
value Product identifier value, ONIX field b244
9.3.12. illustration
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
type ONIX field b253
value ONIX field b252
9.3.14. mediaFiles
JSON Field ONIX Code list / information Comment
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.
VLB REST API Specifications 74 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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)
VLB REST API Specifications 75 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
productForm Product form of the related product, ONIX field b012, according to list 7
VLB REST API Specifications 76 / 79
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
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
JSON Field ONIX Code list / information Comment
subtitle ONIX field b029
title ONIX field b203
type title type; ONIX field b202
9.3.21. websites
JSON Field ONIX Code list / information Comment
VLB REST API Specifications 77 / 79
JSON Field ONIX Code list / information Comment
type ONIX field b367, ONIX Codelist / Info 73
url ONIX field b295
Description ONIX field b294
9.3.22. wholesalers
JSON Field ONIX Code list / information Comment
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
VLB REST API Specifications 78 / 79
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.
VLB REST API Specifications 79 / 79
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.
Please regard the values in the „type“ definition oft he corresponding object.
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.
Please regard the values in the „type“ definition oft he corresponding object.