Authentication, input and response

Request a sustainability advice based on address.

POST https://api.altum.ai/v2/sustainability/apartments

This endpoint allows you to receive response from the Altum AI Sustainability API regarding sustainability and the Ecovalue, using the post code, house number and house addition.

Headers

Name	Type	Description
Content-Type	string	application/json
x-api-key*	string	Unique API Key from Altum. Create one via Mopsus(https://mopsus.altum.ai)

Request Body

Name	Type	Description	Default
postcode*	string	zip code in six character format e.g. 1234AB
housenumber*	integer	house number of the object e.g. 1
houseaddition	string	addition to the house number e.g. A
position	integer	1 = 'Corner ground floor' 2 = 'In between ground floor' 3 = 'Corner mid floor' 4 = 'In between mid floor' 5 = 'Corner top floor' 6 = 'In between top floor' 7 = 'Entire top floor'	3
floors	integer	Does the unit has one or more floors? 1 = 'Single' 2 = 'Multiple'	1
back_facade	boolean	Does the unit has as back facade? false = no true = yes	false
build_year	integer	build year of the property
inner_surface_area	float	square meter surface area
sub_type	integer	1 = 'Galerijflat' 2 = 'Portiekflat' 3 = 'Corridorflat' 4 = 'Maisonnette' 5 = 'Benedenwoning' 6 = 'Bovenwoning' 7 = 'Portiekwoning
wall_insulation	integer	see Measures
floor_insulation	integer	see Measures
roof_insulation	integer	see Measures
living_room_windows	integer	see Measures
bedroom_windows	integer	see Measures
installation	integer	see Measures
shower	integer	see Measures
ventilation	integer	see Measures
solar_panels	list	see Measures
cooling	integer	Is there a cooling system present? 1 = No cooling 2 = Air conditioning unit, direct air cooling Default	1
electric_cooking	integer	What is used for cooking? 1 = Gas stove 2 = Electric stove	2 if Installation in [6,7], Else 1
gas_usage	float	overwrites estimated yearly gas consumption in m3
heat_usage	float	overwrites specified yearly heat consumption in GJ.
electricity_usage	float	overwrites specified yearly electricity consumption in KWh
electricity_generation	float	total yearly electricity yield of solar panels in kWh. Net usage = consumption - yield
inhabitants	integer	number of people living in the house
minimum_solar_panels	integer	The minimum number of new panels to be placed
search_criteria	integer	1 = lowest investment costs 2 = lowest energy costs 3 = highest return on investment 4 = lowest beng2 (highest label)	3
max_investment	integer	maximum investment, use 0 for unlimited
target_label	string	desired target energy label - default is energy label A or D
natural_gas	integer	1 = no filter 2 = natural gas mandatory 3 = natural gas free
district_heating_allowed	boolean	false = not allowed true = allowed	false
heatpump_insulation_req	integer	1 = no minimum requirement 2 = envelope, including glass min 2 3 = house meets “standaard”	3
lock_measures	array	lock measures excluded from calculation
exclude_measure	array	TBA
exclude_vat	boolean	Prices are with or without VAT included. false = VAT included true = VAT excluded	false
cost_indicators	dict	see Cost indicators
wall_filters	dict	see Measure filters
roof_filters	dict	see Measure filters
floor_filters	dict	see Measure filters
custom_costs	integer	TBA
fetch_definitive_label	integer	activate fetching of definitive label from EP-online with 1	0
energylabel_strict	integer	enable strict search of results within target_label with 1	0
improvement_costs	array	TBA
eco_delta	boolean	disable fetching of ecovalue with 0	1
replace_windowframes		TBA

Specifying both the position and the floors of the apartment is recommended for optimal results.

200: OK Successful response

{
  "tip": null,
  "warnings": [
    {
      "code": "11",
      "description": "Current building with energy label C already meets default target_label A."
    }
  ],
  "address": {
    "housenumber": 227,
    "postcode": "3024XL",
    "houseaddition": "B",
    "street": "Willem Buytewechstraat",
    "city": "Rotterdam",
    "location": {
      "lat": 51.90761152288453,
      "lon": 4.451398538183942
    }
  },
  "building": {
    "build_year": 1927,
    "inner_surface": 74,
    "floor_surface": 0,
    "roof_surface": 0,
    "wall_surface": 50.2,
    "glass_living_room_surface": 13.4,
    "number_of_doors": 5,
    "floors": "Single",
    "main_type": "Appartement",
    "sub_type": null
  },
  "label": {
    "current": "C",
    "potential": "B"
  },
  "provided_label": {
    "temporary": "G",
    "definitive": null,
    "definitive_type": null,
    "definitive_validity": null
  },
  "BENG2": {
    "current": 245,
    "potential": 181
  },
  "meta": null,
  "CO2": {
    "current": 2357,
    "potential": 2141
  },
  "financial": {
    "total_investment": 2309,
    "total_saving": 164,
    "months_to_pay_off": 168,
    "eco_value": 0,
    "savings_monthly": 14,
    "energy_cost_monthly": {
      "current": 175,
      "potential": 161
    },
    "energy_cost_yearly": {
      "current": 2096,
      "potential": 1932
    },
    "return_on_investment": "0.52%",
    "loan": {
      "monthly_payment": 10
    }
  },
  "gas_usage": {
    "current": 888,
    "potential": 769
  },
  "electricity_usage": {
    "current": 2262,
    "potential": 2255
  },
  "city_heating_usage": {
    "current": 0,
    "potential": 0
  },
  "solar_panel_yield": {
    "current": 0,
    "potential": 0
  },
  "energy_prices": {
    "variable_gas_price": 1.359,
    "variable_electricity_price": 0.27,
    "solarpanel_watt_peak_per_m2": 250
  },
  "solar_panels": {
    "current": null,
    "potential": null
  },
  "measures": {
    "wall_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 2
      },
      "after": {
        "desc": "Goed",
        "value": 3,
        "points": 5
      },
      "investment": 2309,
      "savings": 164,
      "co2_reduce": 215,
      "BENG2": "100",
      "gas_savings": 119,
      "electricity_savings": 7
    },
    "floor_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "roof_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "living_room_windows": {
      "before": {
        "desc": "Enkel glas",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Enkel glas",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "installation": {
      "before": {
        "desc": "HR combi ketel",
        "value": 4,
        "points": 15
      },
      "after": {
        "desc": "HR combi ketel",
        "value": 4,
        "points": 15
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "shower": {
      "before": {
        "desc": "Geen Douche WTW",
        "value": 1,
        "points": null
      },
      "after": {
        "desc": "Geen Douche WTW",
        "value": 1,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "cooling": {
      "before": {
        "desc": "No cooling",
        "value": 1,
        "points": null
      },
      "after": {
        "desc": "No cooling",
        "value": 1,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "ventilation": {
      "before": {
        "desc": "Natuurlijke ventilatie",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Natuurlijke ventilatie",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "solar_panels": {
      "before": {
        "desc": "0",
        "value": 0,
        "points": null
      },
      "after": {
        "desc": "0",
        "value": 0,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "electric_cooking": {
      "before": {
        "desc": "Gas stove",
        "value": 1,
        "points": null
      },
      "after": {
        "desc": "Gas stove",
        "value": 1,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    }
  },
  "response_meta": null
}

400: Bad Request Unsuccessful response

401: Unauthorized No access

422: Unprocessable Entity Wrong input format

500: Internal Server Error Service is not available and/or down

403: Forbidden Forbidden

301: Moved Permanently Apartment error

Request a sustainability advice based on BagID. TBA

POST https://api.altum.ai/v2/sustainability/apartments/bag

This endpoint allows you to receive response from the Altum AI Sustainability API regarding sustainability and the Ecovalue, using the bag id of the object instead of the post code, house number and house addition.

Headers

Name	Type	Description
Content-Type	string	application/json
x-api-key*	string	API Key from Altum. Create one via Mopsus(https://mopsus.altum.ai)

Request Body

Name	Type	Description	Default
bag_id*	string	16 digits BAG_ID
position	integer	1 = 'Corner ground floor' 2 = 'In between ground floor' 3 = 'Corner mid floor' 4 = 'In between mid floor' 5 = 'Corner top floor' 6 = 'In between top floor' 7 = 'Entire top floor'	3
floors	integer	Does the unit has one or more floors? 1 = 'Single' 2 = 'Multiple'	1
back_facade	boolean	Does the unit has as back facade? false = no true = yes	false
build_year	integer	build year of the property
inner_surface_area	float	square meter surface area
sub_type	integer	1 = 'Galerijflat' 2 = 'Portiekflat' 3 = 'Corridorflat' 4 = 'Maisonnette' 5 = 'Benedenwoning' 6 = 'Bovenwoning' 7 = 'Portiekwoning
wall_insulation	integer	see Measures
floor_insulation	integer	see Measures
roof_insulation	integer	see Measures
living_room_windows	integer	see Measures
bedroom_windows	integer	see Measures
installation	integer	see Measures
shower	integer	see Measures
ventilation	integer	see Measures
solar_panels	list	see Measures
cooling	integer	Is there a cooling system present? 1 = No cooling 2 = Air conditioning unit, direct air cooling Default	1
electric_cooking	integer	What is used for cooking? 1 = Gas stove 2 = Electric stove	2 if Installation in [6,7], Else 1
gas_usage	float	overwrites estimated yearly gas consumption in m3
heat_usage	float	overwrites specified yearly heat consumption in GJ.
electricity_usage	float	overwrites specified yearly electricity consumption in KWh
electricity_generation	float	total yearly electricity yield of solar panels in kWh. Net usage = consumption - yield
inhabitants	integer	number of people living in the house
minimum_solar_panels	integer	The minimum number of new panels to be placed
search_criteria	integer	1 = lowest investment costs 2 = lowest energy costs 3 = highest return on investment 4 = lowest beng2 (highest label)	3
max_investment	integer	maximum investment, use 0 for unlimited
target_label	string	desired target energy label - default is energy label A or D
natural_gas	integer	1 = no filter 2 = natural gas mandatory 3 = natural gas free
district_heating_allowed	boolean	false = not allowed true = allowed	false
heatpump_insulation_req	integer	1 = no minimum requirement 2 = envelope, including glass min 2 3 = house meets “standaard”	3
lock_measures	array	lock measures excluded from calculation
exclude_measure	array	TBA
exclude_vat	boolean	Prices are with or without VAT included. false = VAT included true = VAT excluded	false
cost_indicators	dict	see Cost indicators
wall_filters	dict	see Measure filters
roof_filters	dict	see Measure filters
floor_filters	dict	see Measure filters
custom_costs	integer	TBA
fetch_definitive_label	integer	activate fetching of definitive label from EP-online with 1	0
energylabel_strict	integer	enable strict search of results within target_label with 1	0
improvement_costs	array	TBA
eco_delta	boolean	disable fetching of ecovalue with 0	1
replace_windowframes		TBA

Specifying both the position and the floors of the apartment is recommended for optimal results.

200: OK Successful response

{
  "tip": null,
  "warnings": [
    {
      "code": "11",
      "description": "Current building with energy label C already meets default target_label A."
    }
  ],
  "address": {
    "housenumber": 227,
    "postcode": "3024XL",
    "houseaddition": "B",
    "street": "Willem Buytewechstraat",
    "city": "Rotterdam",
    "location": {
      "lat": 51.90761152288453,
      "lon": 4.451398538183942
    }
  },
  "building": {
    "build_year": 1927,
    "inner_surface": 74,
    "floor_surface": 0,
    "roof_surface": 0,
    "wall_surface": 50.2,
    "glass_living_room_surface": 13.4,
    "number_of_doors": 5,
    "floors": "Single",
    "main_type": "Appartement",
    "sub_type": null
  },
  "label": {
    "current": "C",
    "potential": "B"
  },
  "provided_label": {
    "temporary": "G",
    "definitive": null,
    "definitive_type": null,
    "definitive_validity": null
  },
  "BENG2": {
    "current": 245,
    "potential": 181
  },
  "meta": null,
  "CO2": {
    "current": 2357,
    "potential": 2141
  },
  "financial": {
    "total_investment": 2309,
    "total_saving": 164,
    "months_to_pay_off": 168,
    "eco_value": 0,
    "savings_monthly": 14,
    "energy_cost_monthly": {
      "current": 175,
      "potential": 161
    },
    "energy_cost_yearly": {
      "current": 2096,
      "potential": 1932
    },
    "return_on_investment": "0.52%",
    "loan": {
      "monthly_payment": 10
    }
  },
  "gas_usage": {
    "current": 888,
    "potential": 769
  },
  "electricity_usage": {
    "current": 2262,
    "potential": 2255
  },
  "city_heating_usage": {
    "current": 0,
    "potential": 0
  },
  "solar_panel_yield": {
    "current": 0,
    "potential": 0
  },
  "energy_prices": {
    "variable_gas_price": 1.359,
    "variable_electricity_price": 0.27,
    "solarpanel_watt_peak_per_m2": 250
  },
  "solar_panels": {
    "current": null,
    "potential": null
  },
  "measures": {
    "wall_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 2
      },
      "after": {
        "desc": "Goed",
        "value": 3,
        "points": 5
      },
      "investment": 2309,
      "savings": 164,
      "co2_reduce": 215,
      "BENG2": "100",
      "gas_savings": 119,
      "electricity_savings": 7
    },
    "floor_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "roof_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "living_room_windows": {
      "before": {
        "desc": "Enkel glas",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Enkel glas",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "installation": {
      "before": {
        "desc": "HR combi ketel",
        "value": 4,
        "points": 15
      },
      "after": {
        "desc": "HR combi ketel",
        "value": 4,
        "points": 15
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "shower": {
      "before": {
        "desc": "Geen Douche WTW",
        "value": 1,
        "points": null
      },
      "after": {
        "desc": "Geen Douche WTW",
        "value": 1,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "cooling": {
      "before": {
        "desc": "No cooling",
        "value": 1,
        "points": null
      },
      "after": {
        "desc": "No cooling",
        "value": 1,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "ventilation": {
      "before": {
        "desc": "Natuurlijke ventilatie",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Natuurlijke ventilatie",
        "value": 1,
        "points": 0
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "solar_panels": {
      "before": {
        "desc": "0",
        "value": 0,
        "points": null
      },
      "after": {
        "desc": "0",
        "value": 0,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "electric_cooking": {
      "before": {
        "desc": "Gas stove",
        "value": 1,
        "points": null
      },
      "after": {
        "desc": "Gas stove",
        "value": 1,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    }
  },
  "response_meta": null
}

400: Bad Request Unsuccessful response

401: Unauthorized No access

422: Unprocessable Entity Wrong input format

500: Internal Server Error Service is not available and/or down

403: Forbidden Forbidden

301: Moved Permanently error

Request body

Example requests

{
  "postcode": "3024XL",
  "housenumber":227,
  "houseaddition": "B",
  "position": 3,
  "floors": 1
}

{
  "bag_id": "0599010000202307",
  "position": 3,
  "floors": 1
}