Terug naar boven

Muziekweb web service API documentation


Request web service account   |   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)

if we detect misuse of the images, we reserve the right to block access to the images as we deem appropriate.

The ORGinal scan is NOT available.
  • https://media.cdr.nl/COVER/ORG/FRONT/JK90000.jpg (1400x1400 pixels approximately, size can vary)

API


General API


URL https://api.cdr.nl/engine/version
Example https://api.cdr.nl/engine/version
Request type GET
Parameters None
Description Returns a result set containing among other things the version of the web service



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

For classical music there are three types of presentations to consider

  • COMPOSER/PERFORMERS
  • WORK
  • PERFORMANCE

The classical music database is build like a sort of tree. Every branch has more specific information
           Composer
           |
           +---Uniformetitle/Work (made by a composer)
               +
               |
               +---Performance (performed by a performer, made by a composer)
         

Search API

(1)URL https://api.cdr.nl/singleSearch/singleSearch.xml
Example https://api.cdr.nl/singleSearch/singleSearch.xml?q=madonna&resultCount=10
Request type GET
Parameters Required
q the data to search for. You can enter anything here. When a result is found it will be returned.

optional
realtime=[1|0] when speed is essential (for example when showing a response as a user types) set realtime to 1. This also limits the results to a max of 10 answers, perfect for a type as you go result.
resultCount=x number of results. Default is 10 and maximum is 50

Paging through the data with rangeStart and rangeEnd is not available here!
Description Initially find the right data based on what the user typed.
This call is the one where you start most of the time.
Paging is NOT supported here! After this call we expect the user to choose a result or page through one of the resultsets.


(2)URL https://api.cdr.nl/singleSearch/singleSearch-Paging.xml
Example https://api.cdr.nl/singleSearch/singleSearch-Paging.xml?q=madonna&searchFilter=artist&sortField=ARTIST&rangeStart=1&rangeEnd=20
Request type GET
Parameters Required
q the data to search for, usually the same as used in (1)

seachFilter=[artist|popularalbum|popularsong|composer|performer|classicalwork|classicalperformance|classicalalbum||label]

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[ [ARTIST|COMPOSER|PERFORMER] | [CATALOGNUMBER|RELEASEDATE|ALBUMTITLE|SONGTITLE|WORKTITLE|ARTIST| RATING] | [WORKTITLE||ARTIST|COMPOSER|PERFORMER]|[LABELNAME] ]
SCORE is the default
Description After the user choses a "searchFilter", we can show all the information found under this filter. Paging support is provided.

This call can be the second call when a user has selected a "filter". This call allows you to page through more of the results.
searchFilter=


Specific popular API for showing "lists"

(1)URL https://api.cdr.nl/link/popularArtistLink.xml
Example https://api.cdr.nl/link/popularArtistLink.xml?performerLink=M00000023349&rangeStart=1&rangeEnd=20
Request type GET
Parameters Required
performerLink=xyyyyyyyyyyy the unique code assigned to a performer. It starts with a letter M and is followed by a 11 digit number.

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[SCORE|RATING|ARTIST|RELEASEDATE|ALBUMTITLE|SONGTITLE]
Description Gives a list of albums from one (popular) artist.
This is an ALBUM presentation.


(2)URL https://api.cdr.nl/link/popularUniformTitleLink.xml
Example https://api.cdr.nl/link/popularUniformTitleLink.xml? uniformTitleLink=U00000878048&sortField=RELEASEDATE&rangeStart=1&rangeEnd=20
Request type GET
Parameters Required
uniformTitleLink=xyyyyyyyyyyy the unique code assigned to a uniformetitle/worktitle. It starts with a letter U and is followed by a 11 digit number.

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[SCORE|RATING|ARTIST|RELEASEDATE|SONGTITLE]
Description Gives a list album where the same track can be found. This is a SONG presentation.

(3)URL https://api.cdr.nl/link/labelLink.xml
Example https://api.cdr.nl/link/labelLink.xml?labelLink=L00000000178
Request type GET
Parameters Required
labellink=xyyyyyyyyyyy the unique code assigned to a label. It starts with a letter L and is followed by a 11 digit number.

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[SCORE|RATING|ARTIST|RELEASEDATE|SONGTITLE]
Description Gives a list albums from the same label. This is a ALBUM presentation.



Specific Classical API for showing "lists"

(1)URL https://api.cdr.nl/link/classicalWorkComposerLink.xml
Example https://api.cdr.nl/link/classicalWorkComposerLink.xml?performerLink=M00000239575&sortField=WORK&rangeStart=1&rangeEnd=20
Request type GET
Parameters Required
performerLink =xyyyyyyyyyyy the unique code assigned to a composer. It starts with a letter M and is followed by a 11 digit number.

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[SCORE|WORK]

Optional
letter=[a-z] for quick jump in the resultset, especially handy for composer which have made lots of works (eg. Bach).
Description Return 2 types of results. A alphabetic list to quicklist jump to different parts of the result set (using a letter).
A list of unique works made by the composer.
This is a WORK presentation.


(2)URL https://api.cdr.nl/link/classicalPerformancePerformerLink.xml
Example https://api.cdr.nl/link/classicalPerformancePerformerLink.xml?performerLink=M00000246386&sortField=WORK&rangeStart=1&rangeEnd=20
Request type GET
Parameters Required
performerLink =xyyyyyyyyyyy the unique code assigned to a performer. It starts with a letter M and is followed by a 11 digit number.

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[SCORE|WORK]
Description A list of tracks (performances) the performer has done.
This is a PERFORMANCE presentation.


(3)URL https://api.cdr.nl/link/classicalPerformanceUniformTitleLink.xml
Example https://api.cdr.nl/link/classicalPerformanceUniformTitleLink.xml?uniformTitleLink=U00000594401&sortField=WORK&rangeStart=1&rangeEnd=20
Request type GET
Parameters Required
uniformTitleLink=xyyyyyyyyyyy the unique code assigned to a uniformetitle/worktitle. It starts with a letter U and is followed by a 11 digit number.

rangeStart=x where x is a number
rangeEnd=x where x is a number
The difference between these two values can not be larger than 100

optional
sortField=[SCORE|RATING|PERFORMER|COMPOSER|RELEASEDATE|SONGTITLE]
Description A list of tracks (performances) by (different) performers of the same uniforme title.
This is a PERFORMANCE presentation.



Detail API

URL https://api.cdr.nl/v2/search/albumInformation.xml
Example https://api.cdr.nl/v2/search/albumInformation.xml?albumID=JK90000
Request type GET
Parameters Required
albumID, the unique code assigned to an album
Description Retrieve all the information available for an album.
Basic album information, tracks and lots of other information


URL https://api.cdr.nl/link/performerInfo.xml
Example https://api.cdr.nl/link/performerInfo.xml?performerLink=M00000016837
Request type GET
Parameters Required
performerLink, the unique code assigned to a performer
Description Retrieve all the information available about a performer.
It DOESN'T give you a biografie of all the albums a performer has done.
Look for that at popularArtistLink.xml or classicalWorkComposerLink.xml / classicalPerformancePerformerLink.xml api call.


URL https://api.cdr.nl/link/uniformTitleInfo.xml
Example https://api.cdr.nl/link/uniformTitleInfo.xml?uniformTitleLink=U00000581596
Request type GET
Parameters Required
UniformTitleLink, the unique code assigned to a track/work
Description Retrieve all the information available about a track/work.
It DOESN'T give you a list of all the albums where this track/work is located.
Look for that at popularUniformTitleLink.xml or classicalPerformanceUniformTitleLink.xml api call.


URL https://api.cdr.nl/link/labelInfo.xml
Example https://api.cdr.nl/link/labelInfo.xml?labelLink=L00000000178
Request type GET
Parameters Required
labelLink, the unique code assigned to a label
Description Retrieve all the information available about a label, which isn't much.
It DOESN'T give you a list of all the albums from this label.
Look for that at labelLink.xml api call.


URL https://api.cdr.nl/v1/Fingerprint/TrackInfo.xml
Example https://api.cdr.nl/v1/Fingerprint/TrackInfo.xml?FingerTrackID=7DABDC70FEA2EFD5
Request type GET
Parameters Required
FingerTrackID, the unique code assigned to a track as defined in the fingerprint database.
Description Retrieves the track information, which belongs to the fingertrackid.

This api is specifically for use with the Fingerprinting project hosted at github https://github.com/nelemans1971/AudioFingerprinting and the supplied fingerprinting database. This fingerprint database contains the usable fingertrackid's.