Documentation

Authentication

Every API application needs to obtain an API key. You can apply for a key here. If you have applied for an API key, you will find this key in the email we sent you after the registration. The private key is used to provide extra authentication through the argument api_sig and consists of the md5 sum of the private key and a signature. In this example, our private key and signature are:

private key = 56983djf3872q5e6r
signature = b26271b6f753

Concat the private key and signature (in this order). The MD5 sum of "56983djf3872q5e6rb26271b6f753" will result in:

3acc597ce32c848281eb942a9dcbe8e5

This value needs to be added to the request string, as well as the parameter api_sig

Note: The api_sig must be unique in every call. We suggest you use the UNIX timestamp in microseconds (one millionth (10^-6) of a second) or use a function to create an unique ID everytime.

<?php

	$private_key = "56983djf3872q5e6r";
	$signature = microtime();
	$api_sig = md5($private_key.$signature);

?>

Encoding

Every API expects all data to be UTF-8 encoded. More information about UTF-8

Response Formats

By default the API will return data in XML. The following response formats are available:

XML
JSON

Rate Limit

By default we use a rate limit of 10.000 calls per hour. You can check your current rate by calling the method getCurrentRate.

Error codes

1: Invalid API key: The API key that was provided is invalid
2: Invalid API signature: The API signature that was provided is invalid
3: Unknown method: The method that was called is unknown
4: Invalid country: The country that was provided is invalid
5: Unsupported format: The format that was provided is invalid
6: Rate limit exceeded: Your Application made to many calls and is therefore blocked
7: Invalid language: The language that was provided is invalid
8: API signature was not unique: The API signature that was provided, was already used by the API key. Every time a call is made, the signature has to be unique.
21: Please specify a firstname or fullname: There was no firstname or fullname provided
22: Please specify a set, a category or a source: There was no set, category or source provided