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 compare succesfully, you need a set of general parameters and a set of parameters based on the producttype 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
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
Postalcode zip no numeric Valid Belgian postal code
Sort method sort no numeric Sort method
Detaillevel detaillevel no array Level of detail in response (see detaillevel-chapter)
Grouping grouping no string Grouping of results "productgroup" (default) / "supplier"
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
Netmanager dnb no string Netmanager
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)
Solar panels has_solar no numeric 1: yes, client has solar panels installed. Empty or 0, he does not have solar panels (default)
Solar kW capacity solar_capacity no numeric Only used when has_solar=1. Empty or 0, average kW will be used. If set, given kW will be used (Eg. 3.5). Only used as from 1/7/2015
Test Solar kW capacity force_solar_capacity no 1 or 0 Hack to force solar capacity calculation, even before live-date 1/7/2015
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)

The following method is deprecated since 1/6/2015. The MRU type and usage will be now auto-detected by the API, based on usages provided.

Name Parameter Required Type Description
Meter reading unit type tc yes tc_dn - tc_de - tc_d - tc_dne Type of meter (tc_dn : day/night, tc_de : day+ excl. night , tc_d : day , tc_dne : day/night+excl. night )
Exclusive night tc_ddu yes string Usage during the night

Depending on the meter reading unit type, following parameters are required*

Meter reading unit: DAY/NIGHT: tc_dn
Name Parameter Required Type Description
Usage day tc_dndu yes string Usage during the day
Usage night tc_dnnu yes string Usage during the night
Meter reading unit: DAY / excl. NIGHT: tc_de
Name Parameter Required Type Description
Day tc_dedu yes string Usage during the day
Exclusive night tc_denou yes string Usage exclusive during the night
Meter reading unit: DAY/NIGHT + excl. night: tc_dne
Name Parameter Required Type Description
Usage day tc_dnedu yes string Usage during the day
Usage night tc_dnenu yes string Usage during the night
Usage exclusive night tc_dnenou yes string Usage exclusive during the night
Meter reading unit: DAY: tc_d
Name Parameter Required Type Description
Usage day tc_ddu yes string Usage during the day

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
Netmanager dnb no string Netmanager
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.

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
Netmanager dnb no string Netmanager
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)
Solar panels has_solar no numeric 1: yes, client has solar panels installed. Empty or 0, he does not have solar panels (default)
Solar kW capacity solar_capacity no numeric Only used when has_solar=1. Empty or 0, average kW will be used. If set, given kW will be used (Eg. 3.5). Only used as from 1/7/2015
Test Solar kW capacity force_solar_capacity no 1 or 0 Hack to force solar capacity calculation, even before live-date 1/7/2015
Situation situation no numeric 1=New, 2=Move, 3=Switch, 4=Urgent | Indicator of user situation

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 tariffplans with reduced offerings for calling to family of company collegues
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 kwh / m3 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 kwh / m3 Min. download volume in GB (-1 for unlimited)
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

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 detaillevel 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'
'tc' => 'tc_d'
'tc_ddu' => '4000');

// do the compare
$compare_result = $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 compare
$compare_result = $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