Introduction to Aanbieders.be API

The Aanbieders.be API provides a HTTP based interface to our comparison engine http://www.aanbieders.be. Using it, you'll be able to request comparisons, product information, supplier information or place an order.

Which resources are available?

Currently the API exposes these resources:

The products resource gives access to all the properties of the various products supported by Aanbieders.be. The compare resource allows to deduct those products that best match specific situations. The orders resource allow to place orders in our system with your internal affiliate code The suppliers resource gives access to all suppliers on Aanbieders.be The options resource gives access to all options on Aanbieders.be The promotions resource gives access to all promotions on Aanbieders.be The reviews resource gives access to all reviews on Aanbieders.be

Both resources depend on incoming parameters that need to be specified for each request. The API is stateless meaning that no information is retained between requests.

How does the API work?

This is a bird's eye view on how the API is to be used. For detailed information please consult the various sections summarized in the Help menu on the left.

First of all you need to be registered to be able to use the API. Upon successfull registration you receive two alphanumerical keys: a public key and a private key. The public key has to be provided with each request. The private key is distributed only once, namely after registration and is never to be distributed again. Both keys are necessary to calculate an API key that , together with the public key, is to be provided with each request.

As briefly explained the API uses the standard HTTP protocol. Accessing the resources is done building and sending standard HTTP requests to our host. Depending on the resource different HTTP Request Methods are used:

Resource HTTP format URL.format Description
Products GET /products.json Returns a complete or limited list of products
Products GET /products/123.json Returns one specific product
Compare GET /comparison.json Returns the result of a comparison of products
Orders POST /orders.json Places an order in the system
Suppliers GET /suppliers.json Returns a list with suppliers based on given parameters

Request

Additionally to the public key and the API key a number of parameters have to be set in the request to the chosen resource. Some of the parameters are required and will fire a HTTP error if not present. Other parameters are optional and determine the level of detail of the repsonse ( e.g. when accessing the 'products' resource, providing a supplier id will limit the returned product information to the products belonging to that supplier. ) So for example : we want the information of the products of type 'internet' with id 2 and 3.

The REST based request would look like this :

http://HOST/products.json?cat=internet&productid=2+3&lang=nl&sg=consumer&key=xxxxxx&apikey=xxxxxx

Respose

As we can see the url we use complies with the first HTTP request method mentioned in the table earlier: http://HOST/products.json + Please note that 'HOST' needs to be replaced with the official host name provided by Aanbieders.be. + After the url we find the required parameters for this request. E.g; 'cat' defines the type of products , in this case 'internet' and 'lang' defines the language of the returned product information. + The parameter 'productid' limits the returned list of products to teh the products with id 2 and 3. + Please note the parameters 'key'' and 'apikey' which are essential and need be provided with any request to any resource of the API.

The response of this request would look like this:

[{"producttype":"internet","product_id":"2","group_id":"0","segment":"consumer","last_update":"2009-10-02 15:35:08","last_update_timestamp":1254490508,"contract_periods":["12"],"availability":{"flanders":true,"wallonia":true,"brussels":true},"texts":{"name":"ADSL Light","oneliner":"","explanation":"","remarks":""},"links":{"terms_conditions":null,"clickout":"http:\/\/localhost\/www.ab.be\/internet\/providers\/belcenter\/internet\/adsl-light\/bestel"},"supplier":{"supplier_id":"36","name":"Belcenter","logo":{"100x70":{"color":"http:\/\/localhost\/static.ab.be\/brands\/logos\/no_logo.gif","grayscale":"http:\/\/localhost\/static.ab.be\/brands\/logos\/gray\/no_logo.gif"},"60x42":{"color":"http:\/\/localhost\/static.ab.be\/brands\/midsize\/no_logo.gif","grayscale":"http:\/\/localhost\/static.ab.be\/brands\/midsize\/gray\/no_logo.gif"},"80x30":{"color":"http:\/\/localhost\/static.ab.be\/brands\/thumbs\/no_logo.gif","grayscale":"http:\/\/localhost\/static.ab.be\/brands\/thumbs\/gray\/no_logo.gif"}}},"options":[],"promotions":[],"specifications":{"volume":{"value":1,"unit":"GB"},"download":{"value":1024,"unit":"Mbps"},"upload":{"value":256,"unit":"Mbps"},"fixed_ip":{"value":"0","unit":""},"technology":{"value":"adsl","unit":""},"max_computers":{"value":-1,"unit":""},"antispam":{"value":"0","unit":""},"antivirus":{"value":"0","unit":""}},"price":{"monthly":28,"activation":50,"modem":0,"installation_full":0,"installation_diy":0,"line_rental":19.65}},{"producttype":"internet","product_id":"3","group_id":"0","segment":"consumer","last_update":"2009-10-02 15:35:18","last_update_timestamp":1254490518,"contract_periods":["12"],"availability":{"flanders":true,"wallonia":true,"brussels":true},"texts":{"name":"ADSL Starter","oneliner":"","explanation":"","remarks":""},"links":{"terms_conditions":null,"clickout":"http:\/\/localhost\/www.ab.be\/internet\/providers\/belcenter\/internet\/adsl-starter\/bestel"},"supplier":{"supplier_id":"36","name":"Belcenter","logo":{"100x70":{"color":"http:\/\/localhost\/static.ab.be\/brands\/logos\/no_logo.gif","grayscale":"http:\/\/localhost\/static.ab.be\/brands\/logos\/gray\/no_logo.gif"},"60x42":{"color":"http:\/\/localhost\/static.ab.be\/brands\/midsize\/no_logo.gif","grayscale":"http:\/\/localhost\/static.ab.be\/brands\/midsize\/gray\/no_logo.gif"},"80x30":{"color":"http:\/\/localhost\/static.ab.be\/brands\/thumbs\/no_logo.gif","grayscale":"http:\/\/localhost\/static.ab.be\/brands\/thumbs\/gray\/no_logo.gif"}}},"options":[],"promotions":[],"specifications":{"volume":{"value":30,"unit":"GB"},"download":{"value":3328,"unit":"Mbps"},"upload":{"value":384,"unit":"Mbps"},"fixed_ip":{"value":"0","unit":""},"technology":{"value":"adsl","unit":""},"max_computers":{"value":-1,"unit":""},"antispam":{"value":"0","unit":""},"antivirus":{"value":"0","unit":""}},"price":{"monthly":38,"activation":50,"modem":0,"installation_full":0,"installation_diy":0,"line_rental":19.65}}]
<?php echo 'test';exit; ?>

Status codes

Most important are the first line of the response and the body of the response. The first line is the HTTP response code. This tells you if your request is legitimite ( correct key and api key) and the provided parameters are valid.

The status codes implemented by the API are conform the w3c defined codes : http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

For example if the key were to be invalid, the API would return a HTTP response code : HTTP/1.1 400 Bad Request . For a list of the possible response codes of the API please click here. Fortunately we have a correct request defined and the API returns a HTTP/1.1 200 OK telling us that we created a succesfull request and we can go ahead and interprete the body. The body is the actual data we requested for. In this case it is a json encoded array of the two products with id 2 and 3. For a detailed description please consult the documentation of the appropriate resource.

Summary

To summarize how to use the API : 1. Register for a public and a secret key. 2. Create a list of parameters necessary for your request. 3. Perform the request and interprete the results

By now you should have gained a general insight in the possibilities and how the API of Aanbieders.be works.

Your next step could be registering with Aanbieders.be and request the necessary keys. If you already have done that we advise you to go to the next part in the documentation explaining how to create a valid API key.