# Authentication, input and response

## Request a sustainability advice based on address.

<mark style="color:green;">`POST`</mark> `https://api.altum.ai/v2/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

<table><thead><tr><th width="200">Name</th><th width="136.9998779296875">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td>string</td><td>application/json</td></tr><tr><td>x-api-key<mark style="color:red;">*</mark></td><td>string</td><td>Unique API Key from Altum. Create one via Mopsus(https://mopsus.altum.ai)</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th width="216">Name</th><th width="117.99993896484375">Type</th><th width="282.2220458984375">Description</th><th>Default</th></tr></thead><tbody><tr><td>postcode<mark style="color:red;">*</mark></td><td>string</td><td>zip code in six character format e.g. 1234AB</td><td></td></tr><tr><td>housenumber<mark style="color:red;">*</mark></td><td>integer</td><td>house number of the object e.g. 1</td><td></td></tr><tr><td>houseaddition</td><td>string</td><td>addition to the house number e.g. A</td><td></td></tr><tr><td>build_year</td><td>integer</td><td>build year of the property</td><td></td></tr><tr><td>roof_type</td><td>integer</td><td><p>1 = (mostly) sloped roof</p><p>2 = (mostly) flat roof</p><p>3 = part sloped, part flat roof</p></td><td>If no roof type provided and no data is available, a sloped roof is assumed by default.</td></tr><tr><td>inner_surface_area</td><td>float</td><td>square meter surface area</td><td></td></tr><tr><td>house_type</td><td>integer</td><td><p>1 = vrijstaande woning</p><p>2 = 2-onder-1-kapwoning</p><p>3 = hoekwoning</p><p>4 = tussenwoning</p></td><td></td></tr><tr><td>wall_insulation</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>floor_insulation</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>sloped_roof_insulation</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>flat_roof_insulation</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>living_room_windows</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>bedroom_windows</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>installation</td><td>integer</td><td>see <a href="measures">Measures</a></td><td>4</td></tr><tr><td>shower</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>ventilation</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>solar_panels </td><td>list</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>number_of_solar_panels</td><td>integer</td><td>see <a href="measures">Measures</a></td><td></td></tr><tr><td>cooling</td><td>integer</td><td><p>Is there a cooling system present?</p><p>1 = No cooling</p><p>2 = Air conditioning unit, direct air cooling     </p><p>Default</p></td><td><p>1</p><p><br></p></td></tr><tr><td>electric_cooking</td><td>integer</td><td><p>What is used for cooking?</p><p>1 = Gas stove</p><p>2 = Electric stove</p></td><td><p>2 if Installation in [6,7],</p><p>Else 1</p><p><br></p></td></tr><tr><td>inhabitants</td><td>integer</td><td>number of people living in the house</td><td></td></tr><tr><td>gas_usage</td><td>float</td><td>overwrites estimated yearly  gas consumption in m3</td><td></td></tr><tr><td>heat_usage</td><td>float</td><td>overwrites specified yearly heat consumption in GJ.</td><td></td></tr><tr><td>electricity_usage</td><td>float </td><td>overwrites specified yearly electricity consumption in KWh</td><td></td></tr><tr><td>electricity_generation</td><td>float</td><td><p>total yearly electricity yield of solar panels in kWh.</p><p>Net usage = consumption - yield</p></td><td></td></tr><tr><td>minimum_solar_panels</td><td>integer</td><td>The minimum number of new panels to be placed</td><td></td></tr><tr><td>search_criteria</td><td>integer</td><td><p>1 = lowest investment costs</p><p>2 = lowest energy costs</p><p>3 = highest return on investment</p><p>4 = lowest beng2 (highest label)</p></td><td>3</td></tr><tr><td>target_label</td><td>string</td><td>desired target energy label</td><td>A+</td></tr><tr><td>max_investment</td><td>integer</td><td>maximum investment, use 0 for unlimited</td><td></td></tr><tr><td>natural_gas</td><td>integer</td><td>1 = no filter
<br>2 = natural gas mandatory
<br>3 = natural gas free</td><td></td></tr><tr><td>district_heating_allowed</td><td>boolean</td><td><p>0 = not allowed</p><p>1 = allowed</p></td><td>0</td></tr><tr><td>heatpump_insulation_req</td><td>integer</td><td><p>1 = no minimum requirement</p><p>2 = envelope, including glass min 2</p><p>3 = house meets “standaard”</p></td><td>1</td></tr><tr><td>exclude_vat</td><td>boolean</td><td><p>Prices are with or without VAT included.</p><p>0 = VAT included</p><p>1 = VAT excluded</p></td><td>0</td></tr><tr><td>cost_indicators</td><td>dict</td><td>see <a href="cost-indicators">Cost indicators</a></td><td></td></tr><tr><td>wall_filters</td><td>dict</td><td>see <a href="measure-filters">Measure filters</a></td><td></td></tr><tr><td>sloped_roof_filters</td><td>dict</td><td>see <a href="measure-filters">Measure filters</a></td><td></td></tr><tr><td>flat_roof_filters</td><td>dict</td><td>see <a href="measure-filters">Measure filters</a></td><td></td></tr><tr><td>floor_filters</td><td>dict</td><td>see <a href="measure-filters">Measure filters</a></td><td></td></tr><tr><td>energylabel_strict</td><td>integer</td><td>enable strict search of results within target_label with 1</td><td>0</td></tr><tr><td>eco_delta</td><td>boolean</td><td>disable fetching of ecovalue with 0</td><td>1</td></tr><tr><td>lock_measures</td><td>list</td><td>see <a href="lock-measures">Lock measures</a></td><td></td></tr><tr><td>exclude_measures</td><td>list</td><td>see <a href="exclude-measures">Exclude measures</a></td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Successful response" %}

```
{
	"address": {
		"postcode": "2771DS",
		"housenumber": 87,
		"houseaddition": 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 %}

{% tabs %}
{% 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

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