Accessing the COMPARE resource

The compare resource allows to compare various products in the database of Aanbieders.be.

The HTTP method

There is currently one HTTP method that allows to compare producs

Resource HTTP format URL.format Description
Compare GET /compare.json Returns a list of products

Build a valid API KEY

The API KEY is a required parameter and should be present in each request you make. The key is build using a public key, a private key a nonce and a timestamp. See here for a detailed description on how to create a valid api key.

Define the parameters

To create a comparison successfully, you need a set of general parameters and a set of parameters based on the product type you wish to compare for.

General parameters

Name Parameter Required Type Description
Public key key yes string Public key issued to you after registration
API key apikey yes string Calculated key
Unix timestamp timestamp yes string Unix timestamp used to calculate the api key
Nonce nonce yes string Number used only once in the same second used to calculate the api key
Affiliate ID a yes string Affiliate identification ID
Product type cat yes string Type of product
Current supplier cs no numeric id of the current supplier (-1 = Other Supplier as listed, -2 = Unknown, -3 = No Supplier)
Language lang yes nl / fr Language indicator
Segment sg yes consumer / sme Segment indicator
Preferred supplier(s) pref_cs no numeric / array List only products of specific suppliers
Preferred product(s) pref_pids no numeric / array List only specific products
Compare to product id cmp_pid no numeric Compare results with the given product
Exclude Supplier(s) excl_sids no numeric / array Exclude the specified suppliers from the results
Exclude Product(s) excl_pids no numeric / array Exclude the specified products from the results
Zip code zip no numeric Valid Belgian postal code
Sort method sort no numeric Sort method
Detail level detaillevel no array Level of detail in response (see detaillevel-chapter)
Only promo items promo_offers_only no 1 or 0 If 1, only products that have an active promotion are returned
Ignore promotions ignore_promos no 1 or 0 If 1, all promotion offers are not taken into account during calculations
Ignore options ignore_options no 1 or 0 If 1, all additional options are not taken into account during calculations

Electricity parameters

Name Parameter Required Type Description
Usage day du yes integer Usage (day rate) in kWh.
Usage night nu no integer Usage (night rate) in kWh. Default 0. If > 0, MRU type day/night will be used for GRD tarification.
Usage exclusive night nou no integer Usage (exclusive night rate) in kWh. Default 0. If > 0, MRU type + night exclusive will be used for GRD tarification.
Zip code zip yes 4 digits zip code
Net distributor dnb no string Net distributor (netbeheerder)
Tariff type t yes f / i / no Type of tariff ( f : fixed , i : variable, no : none)
Family size f yes integer Number of family members ( >= 0). Ignored for SME request.
Auto incasso d yes numeric 1 : yes, 0: no automatic incasso
Social tariff include_social no numeric 1: yes, include social tariff in comparison. Empty or 0, don't include (default)
Situation situation no numeric 1=New, 2=Move, 3=Switch, 4=Urgent | Indicator of user situation
Green power gp no numeric Minimum % of green energy. (range 0-100)
2nd Home second_home no numeric Is the house a main stay or second home

Solar parameters

There are two ways of calculating the contributions a client has to pay his solar contribution. The default way is by capacity (prosumententarief in Dutch), which is based on the capacity of your solar inverter. This tariff was introduced in 2015 in Flanders and 2020 in Wallonia. The second method is based on the amount of kWh you inject back onto the grid with your solar inverter. This method will be introduced in Flanders on 01/01/2021.

Solar contributions are not included by default and must be activated by setting the has_solar parameter to 1. Other parameters depend on type of calculation that is applicable for the client. For capacity calculations, the solar_calculation_type parameter should be set to capacity and the solar_capacity should be filled in. For injection, the solar_calculation_type parameter should be set to injection and the solar_injection_day and solar_injection_night parameters should be filled out correctly.

Name Parameter Required Type Description
Solar panels has_solar no numeric 1: yes, client has solar panels installed. Defaults to 0.
Solar calculation type solar_calculation_type no enum How should the solar tariff be calculated (options: capacity, injection). Only used when has_solar=1. Defaults to capacity.
Solar kW capacity solar_capacity no numeric Empty or 0, average kW will be used. If set, given kW will be used (Eg. 3.5). Only used when has_solar=1. Only used for capacity calculations.
Solar injection day solar_injection_day no numeric Injection by the solar panels onto the grid during the day, in kWh. Only used when has_solar=1. Only used for injection calculations.
Solar injection night solar_injection_night no numeric Injection by the solar panels onto the grid during the night, in kWh. Only used when has_solar=1. Only used for injection calculations.

Gas parameters

Name Parameter Required Type Description
Usage u yes string Usage
Unit Type ut yes kwh / m3 Unit type
Zip code zip yes 4 digits Zip code
Net distributor dnb no string Net distributor (netbeheerder)
Contract length l no numeric Contract length in number of months
Auto incasso d yes numeric 1 : yes, 0: no automatic incasso
Tariff type t yes f / i / no Type of tariff ( f : fixed , i : variable, no : none)
Family size f yes integer Number of family members ( >= 0). Ignored for SME request.
2nd Home second_home no numeric Is the house a main stay or second home

Dualfuel Packs parameters

Name Parameter Required Type Description
Elec Usage day du yes integer Usage (day rate) in kWh.
Elec Usage night nu no integer Usage (night rate) in kWh. Default 0. If > 0, MRU type day/night will be used for GRD tarification.
Elec Usage exclusive night nou no integer Usage (exclusive night rate) in kWh. Default 0. If > 0, MRU type + night exclusive will be used for GRD tarification.
Gas Usage u yes string Usage
Gas Unit Type ut yes kwh / m3 Unit type
Zip code zip yes 4 digits zip code
Net distributor dnb no string Net distributor
Tariff type t yes f / i / no Type of tariff ( f : fixed , i : variable, no : none)
Family size f yes integer Number of family members ( >= 0). Ignored for SME request.
Auto incasso d yes numeric 1: yes, 0: no automatic incasso
Social tariff include_social no numeric 1: yes, include social tariff in comparison. Empty or 0, don't include (default)
Situation situation no numeric 1=New, 2=Move, 3=Switch, 4=Urgent | Indicator of user situation
2nd Home second_home no numeric Is the house a main stay or second home

Solar parameters

Since dualfuel also includes electricity, solar panels can also be included in the comparison. These parameters are identical to those used in the electricity comparison. Check the chapter on electricity above for more details.

Detaillevel

Detaillevel gives you the possibility to scale down the response array. When you only need texts, you can add texts to your detail level array and will only get the text array in your output.

In this case, you have the choice in:

When you compare with a current product, you will also receive a savings key in your response, which will tell you how much you can save when changing to this product.

Performance tip

To speed up the request, scale down your response as much as possible with the detaillevel parameter. Texts can be quite large and will create a larger json-file to send over HTTP. Only request the information you really need!

Examples

Now let's put all the elements together and build some REST url:

Example : compare products of type 'electricity'

$params = array(
    'sg'            => 'consumer',
    'lang'          => 'nl',
    'cat'           => 'electricity',
    't'             => 'f',
    'zip'           => '3540',
    'du'            => '4000',
);

// do the comparison
$comparisonResult = $client->compare( $params );

Example : compare products of type 'gas'

$params = array(
    'sg'            => 'consumer',
    'lang'          => 'nl',
    'cat'           => 'gas',
    'u'             => '4000',
    'ut'            => 'kwh',
    'zip'           => '3540',
    't'             => 'no',
    'd'             => '0',
);

// do the comparison
$comparisonResult = $client->compare( $params );

Results

Now perform a HTTP POST using your generated REST url and catch the result. This could be as simple as copying the rest url into your browser's address bar. While this could be perfect for a test, you will want to write a script that calculates the api key, builds the URI and preforms a GET while catching and interpreting the response.

HTTP/1.1 200: success

{"num_results":2,"comparison_id":6227516,"results":[{"ranking":1,"product":{"producttype":"electricity","product_id":"84","group_id":"0","segment":"consumer","last_update":"2012-02-09 23:19:54","last_update_timestamp":1328825994,"contract_periods":["12"],"availability":{"flanders":true,"wallonia":true,"brussels":false},"texts":{"name":"Eco","oneliner":"Kies voor Essent Eco: groene energie die het milieu en uw budget spaart.",,"links":{"terms_conditions":null,"clickout":"http:\/\/localhost\/www.ab.be\/energie\/energieleveranciers\/essent\/elektriciteit\/eco\/bestel?cid=6227516"},"supplier":{"supplier_id":"8","name":"Essent","logo":{"100x70":{"color":"http:\/\/static.econtract.be\/brands\/logos\/no_logo.gif","grayscale":"http:\/\/static.econtract.be\/brands\/logos\/gray\/no_logo.gif"},"60x42":{"color":"http:\/\/static.econtract.be\/brands\/midsize\/no_logo.gif","grayscale":"http:\/\/static.econtract.be\/brands\/midsize\/gray\/no_logo.gif"},"80x30":{"color":"http:\/\/static.econtract.be\/brands\/thumbs\/no_logo.gif","grayscale":"http:\/\/static.econtract.be\/brands\/thumbs\/gray\/no_logo.gif"}}},"options":[],"promotions":[{"promotion_id":"9","is_permanent":true,"validity_duration":"-1","start_date":null,"end_date":null,"start_date_timestamp":null,"end_date_timestamp":null,"acquisition_offer":true,"retention_offer":true,"texts":{"":{"name":"Betaal nu via domicili\u00ebring en u krijgt 12 euro korting.","description":"
<

ul class=\"square\">\r\n\t

\r\n\t\t12 euro korting<\/strong> bij betaling via domiciliëring<\/li>\r\n<\/ul>"}},"links":{"":{"conditions":"Eenmalige korting (BTW incl.) per facturatieadres verrekend.","banner":""}},"specifications":{"key":"12"},"exclusion_list":[]}],"specifications":{"tariff_type":{"value":"Vast tarief","unit":""},"green_origin":{"value":"100.00","unit":"%"},"energy_cost":[{"TH":{"kwh":{"value":0.068,"unit":""},"fixed":{"value":40,"unit":""}},"HI":{"kwh":{"value":0.0818,"unit":""},"fixed":{"value":40,"unit":""}},"LO":{"kwh":{"value":0.0573,"unit":""}},"LOX":{"kwh":{"value":0.0568,"unit":""},"fixed":{"value":25,"unit":""}}}],"taxes":{"flanders":{"green_tax":{"value":"0.01142240","unit":""},"wkk_tax":{"value":"0.00347270","unit":""}},"wallonia":{"green_tax":{"value":"0.01905750","unit":""},"raccordement_tax":{"value":0.0075,"unit":""}},"brussels":{"green_tax":{"value":"0.00000000","unit":""}}}},"price":{"share":"0.00"}},"applied_options":null,"applied_promotions":["9"],"pricing":{"yearly":{"price":831.823428,"promo_price":819.823428}}},{"ranking":2,"product":{"producttype":"electricity","product_id":"78","group_id":"0","segment":"consumer","last_update":"2012-02-01 10:06:17","last_update_timestamp":1328087177,"contract_periods":["12"],"availability":{"flanders":true,"wallonia":true,"brussels":false},"texts":{"name":"Click","oneliner":"Kies Luminus Click en u heeft een jaar gemoedsrust met een vaste energieprijs.","remarks":""},"links":{"terms_conditions":null,"clickout":"http:\/\/localhost\/www.ab.be\/energie\/energieleveranciers\/luminus\/elektriciteit\/click\/bestel?cid=6227516"},"supplier":{"supplier_id":"10","name":"Luminus","logo":{"100x70":{"color":"http:\/\/static.econtract.be\/brands\/logos\/no_logo.gif","grayscale":"http:\/\/static.econtract.be\/brands\/logos\/gray\/no_logo.gif"},"60x42":{"color":"http:\/\/static.econtract.be\/brands\/midsize\/no_logo.gif","grayscale":"http:\/\/static.econtract.be\/brands\/midsize\/gray\/no_logo.gif"},"80x30":{"color":"http:\/\/static.econtract.be\/brands\/thumbs\/no_logo.gif","grayscale":"http:\/\/static.econtract.be\/brands\/thumbs\/gray\/no_logo.gif"}}},"options":[],"promotions":[],"specifications":{"tariff_type":{"value":"Vast tarief","unit":""},"green_origin":{"value":"100.00","unit":"%"},"energy_cost":[{"TH":{"kwh":{"value":0.0641,"unit":""},"fixed":{"value":45,"unit":""}},"HI":{"kwh":{"value":0.0678,"unit":""},"fixed":{"value":55,"unit":""}},"LO":{"kwh":{"value":0.0557,"unit":""}},"LOX":{"kwh":{"value":0.0557,"unit":""},"fixed":{"value":0,"unit":""}}}],"taxes":{"flanders":{"green_tax":{"value":"0.01140000","unit":""},"wkk_tax":{"value":"0.00350000","unit":""}},"wallonia":{"green_tax":{"value":"0.01910000","unit":""},"raccordement_tax":{"value":0.0075,"unit":""}},"brussels":{"green_tax":{"value":"0.00000000","unit":""}}}},"price":{"share":"0.00"}},"applied_options":null,"applied_promotions":null,"pricing":{"yearly":{"price":820.491028,"promo_price":820.491028}}}}}]

HTTP/1.1 400 Bad Request

Api error : Not all required parameters are set : Parameter cat is required