Muziekweb web service API documentation

Introduction

The API Muziekweb uses is implemented as a REST (Representational State Transfer) service and can be found at the address below:

• https://api.cdr.nl

Every valid request will give a xml response. The default xml envelope looks like this:

        <?xml version="1.0" encoding="utf-8" ?>
        <Result ErrorCode="0" Description="OK">
          CONTENT when ERRORCODE equals 0
        </Result>
                  

When ErrorCode does not equal 0 the reason can be found in the "Description" attribute.
Access to the web service is protected using basic access authentication. This makes it easy to connect using different clients, including browsers.

Download example in php

The code of a VERY simplified example in php of the implemented api can be download here. The running version can be found here.

Web service account

You can request a test account for the web service. This will give you 1.000 requests per day for a total of 10.000 request. If you need more as a developer please contact us at info@muziekweb.nl. If you want to use our data for production purposes, a license is needed. Please contact us and give a good description what you want to do with our data. If we see a benefit for muziekweb.nl as well an agreement can be made.

PHP code

Example code using php and the Zend rest Client, requesting the version of the web service.

$_WSREST_username = 'username';
$_WSREST_password = 'password';

require_once('Zend/Rest/Client.php');
Zend_Rest_Client::getHttpClient()->setAuth($_WSREST_username, $_WSREST_password);
$config = array(
      'maxredirects'      => 5,
      'strictredirects'   => false,
      'useragent'         => 'Zend_Http_Client/0.1.5',
      'timeout'           => 30,
      'adapter'           => 'Zend_Http_Client_Adapter_Socket',
      'httpversion'       => 1.1
  );
Zend_Rest_Client::getHttpClient()->setConfig($config);
unset($config);

$client = new \Zend_Rest_Client('https://api.cdr.nl/engine/version');
$result = $client->get();

// Show version web service API
echo 'SearchEngine version: <b>'. $result->Result->Version .'</b><br>';          

http/https

Some of the tags in the result sets return urls. Most of the time these links are using the http protocol. The same url also works for https. You can chose which protocol you want to use.

Paging

Paging is done with the parameter rangeStart and rangeEnd. A maximum of 100 results will be return whatever the difference is between rangeStart and rangeEnd. Results will stop after 2000 hits.

Link to album images

There are several different sizes for the album images. Please use the appropriate one. For selecting the right album image you need to know the albumid. This is available in the result set of albums.

• https://media.cdr.nl/COVER/PICO/FRONT/JK90000.jpg (60x60 pixels)
• https://media.cdr.nl/COVER/SMALL/FRONT/JK90000.jpg (120x120 pixels)
• https://media.cdr.nl/COVER/MEDIUM/FRONT/JK90000.jpg (240x240 pixels)
• https://media.cdr.nl/COVER/LARGE/FRONT/JK90000.jpg (400x400 pixels)
• https://media.cdr.nl/COVER/SUPERLARGE/FRONT/JK90000.jpg (800x800 pixels)

• https://media.cdr.nl/COVER/ORG/FRONT/JK90000.jpg (1400x1400 pixels approximately, size can vary)

API

General API

Searching API

Popular and classical music

The Muziekweb database separates popular en classical music. This is because in our view to properly support the users. Classical music needs a different way of looking at the data.

Parameters

Some parameters are used over and over again in the search api.

rangeStart=x where x is a number
rangeEnd=x where x is a number
These two parameters are used to page over the complete result set. The max difference should be no more than 100.

sortField=[ [ARTIST|COMPOSER|PERFORMER] | [CATALOGNUMBER|RELEASEDATE|ALBUMTITLE|SONGTITLE|WORKTITLE|ARTIST| RATING] | [WORKTITLE||ARTIST|COMPOSER|PERFORMER]|[LABELNAME] ]

sortField details

For the different result sets you can sort on different fields. The default (no sortField given) is SCORE and is a combination of popularity and best match. The parameter sortField in many of the API calls has a lot of different fieldnames. Some of the fieldnames are interchangeable. It doesn't matter which you use, internally they are mapped to the appropriate field.

• ARTIST|PERFORMER|COMPOSER are all the same
• ALBUMTITLE|SONGTITLE are all the same

Complexity Search API

We have opted not to implemented the search API as a google like search engine. Instead we chose to give different "views" on the data. In our opinion this gives the user a better way of quickly finding what he or she wants to find.
The search API tries to guess what a user wants to find and gives results based on the typing, most of the time this result should be good enough, when not the API is flexible enough to allow the user to select a different kind of result.
The website Muziekweb.nl uses the same API as presented here, there is no difference!

Presentation of the result sets

The attribute "ResultName" in the tag <ResultInfo> tells you which layout you can use to present the information. There are three presentations to consider for popular searches:

• ARTIST
• ALBUM
• SONG

• COMPOSER/PERFORMERS
• WORK
• PERFORMANCE

           Composer
           |
           +---Uniformetitle/Work (made by a composer)
               +
               |
               +---Performance (performed by a performer, made by a composer)
         

Search API

Specific popular API for showing "lists"

Specific Classical API for showing "lists"

Detail API