Authentication, input and response

Request a sustainability advice based on address.

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

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
post_code*	string	zip code in six character format e.g. 1234AB
house_number*	integer	house number of the object e.g. 1
house_addition	string	addition to the house number e.g. A
inner_surface_area	integer	square meter surface area
build_year	integer	build year of the property
target_label	string	desired target energy label - default is energy label A
installation	integer	current installation - see measures
ventilation	integer	current ventilation - see measures
shower	integer	current shower WTW - see measures
solar_panels	integer	current solar panels in m2 (default) or total watt-peak capacitity in W (see watt_panels) - see measures
house_type	integer	current house-type: 1:semi-detached, 2:corner house, 3:terraced house, 4:detached house and 5:apartment* (*service doesn't return measures for an apartment.)
lock_measures	array	lock measures excluded from calculation
watt_panels	integer	assume solar_panels input is in W (0) or m2 (1). Default = 1
max_investment	integer	maximum investment, use 0 for unlimited
electricity_usage	integer
heat_usage	integer	input current heat usage
gas_usage	integer	if used overwrites estimated gas usage
search_criteria	integer	0 = Lowest investment costs, 1 = Lowest energy costs, 2 = highest financial return on investment, 3 = highest BARe
heat_pump_allowed	boolean	allowed or not allowed to advice to implement a heat pump
replace_boiler	boolean	allowed or not allowed to replace the boiler installation
inhabitants	integer	number of people living in the house
natural_gas	integer	0 = Natural gas allowed, 1 = Natural gas required, 2 = Natural gas not allowed
solar_panels_surface	integer	0 = No panels, 1 = Maximum half of the available space, 2 = Fully covered
heatpump_insulation_req	integer	0 till 3 defined the minium insulation requirement for advice of a heat pump
fetch_definitive_label	integer	activate fetching of definitive label at EP-online with 1, default is 0
energylabel_strict	integer	enable strict search of results within target_label with 1, default is 0
improvement_costs	array	input improvement costs - see cost table
eco_delta	boolean	disable fetching of ecovalue with 0, default is 1
roof_insulation	integer	current roof insulation - see measures
wall_insulation	integer	current wall insulation - see measures
floor_insulation	integer	current floor insulation - see measures
living_room_windows	integer	current living room windows - see measures
bedroom_windows	integer	current bedroom windows - see measures
exclude_measure	array	exclude specific measures - see measures exclusion
minimum_solar_panels	integer	minimum number of solar panels to be included in advice when adviced
solarpanel_watt_peak	integer	watt peak performance of solar panels per sq m2
custom_costs	array	input custom costs - see cost table
replace_windowframes	integer	activate extra costs for glass related codes with 1, see PDF cost table

200: OK Successful response

{
	"address": {
		"house_number": 87,
		"post_code": "2771DS",
		"addition": null,
		"street": "Zuidkade",
		"city": "Boskoop",
		"location": {
			"lat": 52.06839381665532,
			"lon": 4.6580852694533394
		}
	},
	"building": {
		"build_year": 1961,
		"inner_surface": 131.0,
		"floor_surface": 97.0,
		"flat_roof_surface": 0,
		"pitched_roof_surface": 124.4,
		"wall_surface": 150.7,
		"glass_living_room_surface": 24.9,
		"glass_bedrooms_surface": 6.9,
		"type": "vrijstaand"
	},
	"label": {
		"current": "G",
		"potential": "A++++"
	},
	"provided_label": {
		"temporary": "F",
		"definitive": "C",
		"definitive_type": null,
		"definitive_validity": null
	},
	"BENG1": {
		"current": 165,
		"potential": 139
	},
	"BENG2": {
		"current": 422,
		"potential": -1
	},
	"meta": null,
	"energyindex": {
		"current": null,
		"potential": null
	},
	"ELG": {
		"current": null,
		"potential": null
	},
	"comfortscore": {
		"current": 1,
		"potential": 3
	},
	"CO2": {
		"current": 10632,
		"potential": 2564
	},
	"financial": {
		"total_investment": 67638.64,
		"total_saving": 8119.28,
		"months_to_pay_off": 99,
		"eco_value": null,
		"savings_monthly": 677,
		"energy_cost_monthly": 681,
		"loan": {
			"monthly_payment": 280.0
		}
	},
	"usage": {
		"gas": 6059,
		"energy": 4077,
		"city_heating": 0
	},
	"usage_potential": {
		"gas": 0,
		"energy": 903,
		"city_heating": 0
	},
	"energy_prices": {
		"variable_gas_price": 1.144,
		"variable_electricity_price": 0.293,
		"solarpanel_watt_peak_per_m2": 212
	},
	"measures": {
		"wall_insulation": {
			"before": {
				"desc": "Geen",
				"value": 0,
				"points": 2
			},
			"after": {
				"desc": "Geen",
				"value": 0,
				"points": 2
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"floor_insulation": {
			"before": {
				"desc": "Geen",
				"value": 0,
				"points": 0
			},
			"after": {
				"desc": "Goed",
				"value": 2,
				"points": 7
			},
			"investment": 2865.38,
			"saving": 1426,
			"co2_reduce": 2223,
			"BENG2": "20.8%",
			"gas_savings": 1205,
			"electricity_savings": 161
		},
		"roof_insulation": {
			"before": {
				"desc": "Geen",
				"value": 0,
				"points": 0
			},
			"after": {
				"desc": "Goed",
				"value": 2,
				"points": 3
			},
			"investment": 12441.24,
			"saving": 1928,
			"co2_reduce": 3005,
			"BENG2": "28.1%",
			"gas_savings": 1629,
			"electricity_savings": 218
		},
		"living_room_windows": {
			"before": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": 1
			},
			"after": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": 1
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"bedroom_windows": {
			"before": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": null
			},
			"after": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": null
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"ventilation": {
			"before": {
				"desc": "Natuurlijk",
				"value": 0,
				"points": 0
			},
			"after": {
				"desc": "Natuurlijk",
				"value": 0,
				"points": 0
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"solar_panels": {
			"before": {
				"desc": "0",
				"value": 0,
				"points": null
			},
			"after": {
				"desc": "59",
				"value": 59,
				"points": null
			},
			"investment": 21849.7,
			"saving": 3279,
			"co2_reduce": 3705,
			"BENG2": "19%",
			"gas_savings": 0,
			"electricity_savings": 11192
		},
		"instalation": {
			"before": {
				"desc": "HR-combi",
				"value": 4,
				"points": 15
			},
			"after": {
				"desc": "WP bodem combi",
				"value": 7,
				"points": 20
			},
			"investment": 29686.14,
			"saving": 2665,
			"co2_reduce": 4254,
			"BENG2": "64.0%",
			"gas_savings": 6059,
			"electricity_savings": -15438
		},
		"shower": {
			"before": {
				"desc": "Geen Douche WTW",
				"value": 0,
				"points": null
			},
			"after": {
				"desc": "Douche WTW",
				"value": 1,
				"points": null
			},
			"investment": 796.18,
			"saving": 93,
			"co2_reduce": 146,
			"BENG2": "0.4%",
			"gas_savings": 82,
			"electricity_savings": 0
		}
	},
	"response_meta": null
}

400: Bad Request Unsuccessful response

{
  "detail": "There was an error parsing the body"
}

{
  "detail": "Address not found in database, combination of zip code and house number"
}

{
  "detail": "There are no measures to suggest for this combination of input."
}

{
  "detail": "No housing variant with the selected installation options found with which the goal can be reached within the investment limit. Try again with different inputs and/or different search criteria."
}
{
  "detail": "For a given custom cost make sure the parameter 'value' is provided."
}
{
  "detail": "For a given improvement cost make sure all four parameters: 'material', 'work', 'saving_material' and 'saving _work' are provided."
}

401: Unauthorized No access

{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}

422: Unprocessable Entity Wrong input format

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

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

{
	"message": "Internal server error"
}

403: Forbidden Forbidden

{
	"message": "Missing Authentication Token"
}

301: Moved Permanently Apartment error

{
    "detail": "Unable to check apartment."
}

303: See Other house type error

{ 
  "detail": "House type not found in database. Use house_type parameter instead." 
}

Request a sustainability advice based on BagID.

POST https://api.altum.ai/sustainability/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
bag_id*	string	16 digits BAG_ID
inner_surface_area	integer	square meter surface area
build_year	integer	build year of the property
target_label	string	desired target energy label - default is energy label A
installation	integer	current installation - see measures
ventilatiom	integer	current ventilation - see measures
shower	integer	current shower WTW - see measures
solar_panels	integer	current solar panels in m2 (default) or total watt-peak capacitity in W (see watt_panels) - see measures
house_type	integer	current house-type: 1:semi-detached, 2:corner house, 3:terraced house, 4:detached house and 5:apartment* (*service doesn't return measures for an apartment.)
lock_measures	array	lock measures excluded from calculation
watt_panels	integer	assume solar_panels input is in W (0) or m2 (1). Default = 1
max_investment	integer	maximum investment, use 0 for unlimited
electricity_usage	integer	input current electricity usage
heat_usage	integer	input current heat usage
gas_usage	integer	if used overwrites estimated gas usage
search_criteria	integer	0 = Lowest investment costs, 1 = Lowest energy costs, 2 = highest financial return on investment, 3 = highest BARe
heat_pump_allowed	boolean	allowed or not allowed to advice to implement a heat pump
replace_boiler	boolean	allowed or not allowed to replace the boiler installation
inhabitants	integer	number of people living in the house
natural_gas	integer	0 = Natural gas allowed, 1 = Natural gas required, 2 = Natural gas not allowed
solar_panels_surface	integer	0 = No panels, 1 = Maximum half of the available space, 2 = Fully covered
heatpump_insulation_req	integer	0 till 3 defined the minium insulation requirement for advice of a heat pump
fetch_definitive_label	integer	activate fetching of definitive label at EP-online with 1, default is 0
energylabel_strict	integer	enable strict search of results within target_label with 1, default is 0
improvement_costs	array	input improvement costs - see cost table
eco_delta	boolean	disable fetching of ecovalue with 0, default is 1
roof_insulation	integer	current roof insulation - see measures
wall_insulation	integer	current wall insulation - see measures
floor_insulation	integer	current floor insulation - see measures
living_room_windows	integer	current living room windows - see measures
bedroom_windows	integer	current bedroom windows - see measures
exclude_measure	array	0 till 3 defined the minium insulation requirement for advice of a heat pump - see measures exclusion
minimum_solar_panels	integer	minimum number of solar panels to be included in advice when adviced
solarpanel_watt_peak	integer	watt peak performance of solar panels per sq m2
custom_costs	array	input custom costs - see cost table
replace_windowframes	integer	activate extra costs for glass related codes with 1, see PDF cost table

200: OK Successful response

{
	"address": {
		"house_number": 87,
		"post_code": "2771DS",
		"addition": null,
		"street": "Zuidkade",
		"city": "Boskoop",
		"location": {
			"lat": 52.06839381665532,
			"lon": 4.6580852694533394
		}
	},
	"building": {
		"build_year": 1961,
		"inner_surface": 131.0,
		"floor_surface": 97.0,
		"flat_roof_surface": 0,
		"pitched_roof_surface": 124.4,
		"wall_surface": 150.7,
		"glass_living_room_surface": 24.9,
		"glass_bedrooms_surface": 6.9,
		"type": "vrijstaand"
	},
	"label": {
		"current": "G",
		"potential": "A++++"
	},
	"provided_label": {
		"temporary": "F",
		"definitive": "C",
		"definitive_type": null,
		"definitive_validity": null
	},
	"BENG1": {
		"current": 165,
		"potential": 139
	},
	"BENG2": {
		"current": 422,
		"potential": -1
	},
	"meta": null,
	"energyindex": {
		"current": null,
		"potential": null
	},
	"ELG": {
		"current": null,
		"potential": null
	},
	"comfortscore": {
		"current": 1,
		"potential": 3
	},
	"CO2": {
		"current": 10632,
		"potential": 2564
	},
	"financial": {
		"total_investment": 67638.64,
		"total_saving": 8119.28,
		"months_to_pay_off": 99,
		"eco_value": null,
		"savings_monthly": 677,
		"energy_cost_monthly": 681,
		"loan": {
			"monthly_payment": 280.0
		}
	},
	"usage": {
		"gas": 6059,
		"energy": 4077,
		"city_heating": 0
	},
	"usage_potential": {
		"gas": 0,
		"energy": 903,
		"city_heating": 0
	},
	"energy_prices": {
		"variable_gas_price": 1.144,
		"variable_electricity_price": 0.293,
		"solarpanel_watt_peak_per_m2": 212
	},
	"measures": {
		"wall_insulation": {
			"before": {
				"desc": "Geen",
				"value": 0,
				"points": 2
			},
			"after": {
				"desc": "Geen",
				"value": 0,
				"points": 2
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"floor_insulation": {
			"before": {
				"desc": "Geen",
				"value": 0,
				"points": 0
			},
			"after": {
				"desc": "Goed",
				"value": 2,
				"points": 7
			},
			"investment": 2865.38,
			"saving": 1426,
			"co2_reduce": 2223,
			"BENG2": "20.8%",
			"gas_savings": 1205,
			"electricity_savings": 161
		},
		"roof_insulation": {
			"before": {
				"desc": "Geen",
				"value": 0,
				"points": 0
			},
			"after": {
				"desc": "Goed",
				"value": 2,
				"points": 3
			},
			"investment": 12441.24,
			"saving": 1928,
			"co2_reduce": 3005,
			"BENG2": "28.1%",
			"gas_savings": 1629,
			"electricity_savings": 218
		},
		"living_room_windows": {
			"before": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": 1
			},
			"after": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": 1
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"bedroom_windows": {
			"before": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": null
			},
			"after": {
				"desc": "Dubbel glas",
				"value": 1,
				"points": null
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"ventilation": {
			"before": {
				"desc": "Natuurlijk",
				"value": 0,
				"points": 0
			},
			"after": {
				"desc": "Natuurlijk",
				"value": 0,
				"points": 0
			},
			"investment": 0.0,
			"saving": 0,
			"co2_reduce": 0,
			"BENG2": "0%",
			"gas_savings": 0,
			"electricity_savings": 0
		},
		"solar_panels": {
			"before": {
				"desc": "0",
				"value": 0,
				"points": null
			},
			"after": {
				"desc": "59",
				"value": 59,
				"points": null
			},
			"investment": 21849.7,
			"saving": 3279,
			"co2_reduce": 3705,
			"BENG2": "19%",
			"gas_savings": 0,
			"electricity_savings": 11192
		},
		"instalation": {
			"before": {
				"desc": "HR-combi",
				"value": 4,
				"points": 15
			},
			"after": {
				"desc": "WP bodem combi",
				"value": 7,
				"points": 20
			},
			"investment": 29686.14,
			"saving": 2665,
			"co2_reduce": 4254,
			"BENG2": "64.0%",
			"gas_savings": 6059,
			"electricity_savings": -15438
		},
		"shower": {
			"before": {
				"desc": "Geen Douche WTW",
				"value": 0,
				"points": null
			},
			"after": {
				"desc": "Douche WTW",
				"value": 1,
				"points": null
			},
			"investment": 796.18,
			"saving": 93,
			"co2_reduce": 146,
			"BENG2": "0.4%",
			"gas_savings": 82,
			"electricity_savings": 0
		}
	},
	"response_meta": null
}

400: Bad Request Unsuccessful response

{
  "detail": "There was an error parsing the body"
}

{
  "detail": "Address not found in database, combination of zip code and house number"
}

{
  "detail": "There are no measures to suggest for this combination of input."
}

{
  "detail": "No housing variant with the selected installation options found with which the goal can be reached within the investment limit. Try again with different inputs and/or different search criteria."
}

401: Unauthorized No access

{
    'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}

422: Unprocessable Entity Wrong input format

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

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

{
	"message": "Internal server error"
}

403: Forbidden Forbidden

{
	"message": "Missing Authentication Token"
}

301: Moved Permanently Apartment error

{
    "detail": "Unable to check apartment."
}

303: See Other house type error

{ 
  "detail": "House type not found in database. Use house_type parameter instead." 
}

Request body

Example requests

{
    "data": {
    "post_code": "2771DS",
    "house_number": "87",
    "target_label": "A++++",
    "eco_delta": 0
	}
}

{
    "data": {
    "bag_id": "0637010000264937",
    "target_label": "A++++",
    "eco_delta": 0
	}
}