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
Region code re no vl / w / b One of the above region codes in lowercase
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)
Grouping grouping no string Grouping of results "productgroup" (default) / "supplier"
Market Segment market_segment no numeric 0=low-end, 1=mid-range, 2=high-end
QOS Customer Service qos_cs no numeric Min. quality-of-service score (0-100) rating for supplier customer service dept.
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
Greenpeace score greenpeace no numeric Range 0-20

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.

Mobile phone subscription parameters

Name Parameter Required Type Description
Minutes nm no numeric Monthly call minutes
SMS ns no numeric Monthly SMS
Mobile data int no numeric Mobile data MB
Fleet/Family calls fleet no 1 or 0 1: Limits to tariff plans with reduced offerings for calling to family of company colleagues
Max price/month pr no numeric Max monthly fee
Call moment cm no numeric 1: peak, 2: off peak, 0: no preference
Free landline calling f no 1 or 0 If set, calling from mobile to landlines must be included
Zip code zip no 4 digits Zip code (limits offer available in this region)

Internet parameters

Name Parameter Required Type Description
Download Speed s no string Min. download speed in Bps: 1000 Bps = 1Mbps
Download limit dl no Min. download volume in GB (-1 for unlimited)
Belgacom line bl no string 'nf' indicates customer doesn't have an Active fixed line (Belgacom).
SLA sla no numeric Minimum response time ico. technical issues, expressed in hours. (8 or 24). Only for SME
Num. PCs num_pc no numeric How many computers will be using this internet connection
Fixed ip fixed_ip no string 'fixed' for fixed ip address. Empty for any dynamic ip (default)

Internet pack parameters

Name Parameter Required Type Description
Pack type cp no string Pack type: 'int_tel', 'tv_tel', 'int_tel_tv', 'gsm_int_tel_tv', 'int_tv', 'gsm_int_tv'
Download Speed s no string Min. download speed in Bps: 1000 Bps = 1Mbps
Download limit dl no Min. download volume in GB (-1 for unlimited)
Upload speed upload no Min. upload speed in Bps: 1000 Bps = 1Mbps
SLA sla no numeric Minimum response time ico. technical issues, expressed in hours. (8 or 24). Only for SME
Num. PCs num_pc no numeric How many computers will be using this internet connection
Free calling vtf no 'offpeak' / 'peak' 'offpeak' or 'peak' for free calling to fixed lines
Free installation free_install no true/false Show only packs with free installation
Free activation free_activation no true/false Show only packs with free activation
Technology technology no string-array Limit to technologies used as transport: 'dsl' or 'coax'
Market Segment Internet ms_internet no 0,1,2 Show only packs with low-end/mid-range/high-end internet connections
Market Segment TV ms_idtv no 0,1,2 Show only packs with low-end/mid-range/high-end tv connections
Market Segment Fixed Line ms_fixed no 0,1,2 Show only packs with low-end/mid-range/high-end fixe telephony connections
Num. TVs num_tv no integer How many TVs are in the household? (alternative to download limit setting)
Num. Smartphones num_smartphones no integer How many smartphones are in the household? (alternative to download limit setting)
Num. Tablets num_tablets no integer How many tablets are in the household? (alternative to download limit setting)
Family size f no integer Number of family members ( >= 0).

Mobile Internet parameters

Name Parameter Required Type Description
Volume int yes numeric Download volume in MB
Device device yes enum blackberry / ipad / tablet / laptop

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