# 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() |
#### 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](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| ventilation | integer | current ventilation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| shower | integer | current shower WTW - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| solar\_panels | integer | current solar panels in m2 (default) or total watt-peak capacitity in W (see watt\_panels) - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/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](#user-content-fn-1)[^1] |
| 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](https://docs.altum.ai/english/sustainability/sustainability-api/cost-table-input) |
| eco\_delta | boolean | disable fetching of ecovalue with 0, default is 1 |
| roof\_insulation | integer | current roof insulation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| wall\_insulation | integer | current wall insulation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| floor\_insulation | integer | current floor insulation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| living\_room\_windows | integer | current living room windows - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| bedroom\_windows | integer | current bedroom windows - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| exclude\_measure | array | exclude specific measures - see [measures exclusion](https://docs.altum.ai/english/sustainability/sustainability-api/exclude-measures) |
| 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](https://docs.altum.ai/english/sustainability/sustainability-api/cost-table-input) |
| replace\_windowframes | integer | activate extra costs for glass related codes with 1, see PDF [cost table](https://docs.altum.ai/english/sustainability/sustainability-api/cost-table-input) |
{% tabs %}
{% tab title="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
}
```
{% endtab %}
{% tab title="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."
}
```
{% endtab %}
{% tab title="401: Unauthorized No access" %}
```
{
'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}
```
{% endtab %}
{% tab title="422: Unprocessable Entity Wrong input format" %}
```
{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}
```
{% endtab %}
{% tab title="500: Internal Server Error Service is not available and/or down" %}
```
{
"message": "Internal server error"
}
```
{% endtab %}
{% tab title="403: Forbidden Forbidden" %}
```
{
"message": "Missing Authentication Token"
}
```
{% endtab %}
{% tab title="301: Moved Permanently Apartment error" %}
```
{
"detail": "Unable to check apartment."
}
```
{% endtab %}
{% tab title="303: See Other house type error" %}
```
{
"detail": "House type not found in database. Use house_type parameter instead."
}
```
{% endtab %}
{% endtabs %}
## 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() |
#### 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](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| ventilatiom | integer | current ventilation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| shower | integer | current shower WTW - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| solar\_panels | integer | current solar panels in m2 (default) or total watt-peak capacitity in W (see watt\_panels) - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/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](https://docs.altum.ai/english/sustainability/sustainability-api/cost-table-input) |
| eco\_delta | boolean | disable fetching of ecovalue with 0, default is 1 |
| roof\_insulation | integer | current roof insulation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| wall\_insulation | integer | current wall insulation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| floor\_insulation | integer | current floor insulation - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| living\_room\_windows | integer | current living room windows - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| bedroom\_windows | integer | current bedroom windows - see [measures](https://docs.altum.ai/english/sustainability/sustainability-api/measures) |
| exclude\_measure | array | 0 till 3 defined the minium insulation requirement for advice of a heat pump - see [measures exclusion](https://docs.altum.ai/english/sustainability/sustainability-api/exclude-measures) |
| 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](https://docs.altum.ai/english/sustainability/sustainability-api/cost-table-input) |
| replace\_windowframes | integer | activate extra costs for glass related codes with 1, see PDF [cost table](https://docs.altum.ai/english/sustainability/sustainability-api/cost-table-input) |
{% tabs %}
{% tab title="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
}
```
{% endtab %}
{% tab title="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."
}
```
{% endtab %}
{% tab title="401: Unauthorized No access" %}
```
{
'Output': 'Please use https://api.altum.ai or visit https://mopsus.altum.ai to make your request.'
}
```
{% endtab %}
{% tab title="422: Unprocessable Entity Wrong input format" %}
```
{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}
```
{% endtab %}
{% tab title="500: Internal Server Error Service is not available and/or down" %}
```
{
"message": "Internal server error"
}
```
{% endtab %}
{% tab title="403: Forbidden Forbidden" %}
```
{
"message": "Missing Authentication Token"
}
```
{% endtab %}
{% tab title="301: Moved Permanently Apartment error" %}
```
{
"detail": "Unable to check apartment."
}
```
{% endtab %}
{% tab title="303: See Other house type error" %}
```
{
"detail": "House type not found in database. Use house_type parameter instead."
}
```
{% endtab %}
{% endtabs %}
## 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
}
}
```
[^1]: eigen elektriciteitsverbruik is het netto jaarlijkse elektriciteitsverbruik dat resulteert na de aftrek van de totale jaarlijkse eigen opwekking door zonnepanelen. Het is het jaarlijkse verbruik na saldering van de opwekking van aanwezige zonnepanelen.