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 on https://platform.altum.ai

Request Body

Name	Type	Description	Example/Default
postcode*	string	zip code in six character format e.g. 1234AB	1234AB
housenumber*	integer	house number of the object e.g. 1	5
houseaddition	string	addition to the house number e.g. A	C
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'	Default: 1
floors	integer	Does the unit has one or more floors? 1 = 'Single' 2 = 'Multiple'	Default: 1
back_facade	boolean	Does the unit has as back facade? false = no true = yes	Default: false
build_year	integer	build year of the property	1960
inner_surface_area	float	square meter surface area	70
apartment_type	integer	1 = 'Galerijflat' 2 = 'Portiekflat' 3 = 'Maisonnette' 4 = 'Benedenwoning' 5 = 'Bovenwoning' 6 = 'Portiekwoning'	2
wall_insulation	integer	see Measures	2
floor_insulation	integer	see Measures	2
roof_insulation	integer	see Measures	2
living_room_windows	integer	see Measures	2
installation	integer	see Measures	Default: 4
shower	integer	see Measures	Default: 1
ventilation	integer	see Measures	1
solar_panels	list	see Measures
number_of_solar_panels	integer	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	Default: 2 if Installation in [6,7], Else 1
inhabitants	integer	number of people living in the house	Default: 3
gas_usage	float	Overwrites estimated yearly gas consumption in m3	1000
heat_usage	float	Overwrites specified yearly heat consumption in GJ.	45
electricity_usage	float	Overwrites specified yearly electricity consumption in KWh	2600
electricity_generation	float	Total yearly electricity yield of solar panels in kWh. Net usage = consumption - yield	800
minimum_solar_panels	integer	The minimum number of new panels to be placed	4
search_criteria	integer	1 = lowest investment costs 2 = lowest energy costs 3 = highest return on investment 4 = lowest beng2 (highest label)	Default: 3
target_label	string	Desired target energy label	Default: A+
max_investment	integer	The maximum amount (€) to be invested	25000
energylabel_strict	integer	enable strict search of results within target_label with 1	Default: 0
natural_gas	integer	1 = no filter 2 = natural gas mandatory 3 = natural gas free	Default: 1
heat_pump_allowed	boolean	false = not allowed true = allowed	Default: false
district_heating_allowed	boolean	false = not allowed true = allowed	Default: false
heatpump_insulation_req	integer	Minimum requirement on insulation before heatpump is allowed 1 = no minimum requirement 2 = envelope, including glass min level 2 3 = house meets “standaard”	Default: 1
exclude_vat	boolean	Prices are with or without VAT included. false = VAT included true = VAT excluded	Default: 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
eco_delta	integer	Fetching ecovalue 0 = Disable 1 = Enable	Default: 1
lock_measures	list	see Lock measures
exclude_measures	list	see Exclude measures

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

200: OK Successful response

{
  "warnings": [],
  "address": {
    "housenumber": 227,
    "postcode": "3024XL",
    "houseaddition": "B",
    "street": "Willem Buytewechstraat",
    "city": "Rotterdam",
    "location": {
      "lat": 51.9076115229,
      "lon": 4.4513985382
    }
  },
  "building": {
    "build_year": 1927,
    "inner_surface": 74,
    "floor_surface": 74,
    "flat_roof_surface": null,
    "pitched_roof_surface": null,
    "wall_surface": 50.2,
    "glass_living_room_surface": 13.4,
    "glass_bedrooms_surface": null,
    "number_of_doors": 5,
    "apartment_type": "Portiekwoning"
  },
  "label": {
    "current": "C",
    "potential": "A+"
  },
  "accuracy_indicator": 3,
  "provided_label": {
    "temporary": "G",
    "definitive": null,
    "definitive_type": null,
    "definitive_validity": null,
    "definitive_beng2": null
  },
  "BENG2": {
    "current": 191,
    "potential": 87
  },
  "meta": null,
  "CO2": {
    "current": 2095,
    "potential": 2022
  },
  "financial": {
    "total_investment": 17400,
    "total_saving": 32,
    "months_to_pay_off": 6516,
    "eco_value": 39246,
    "savings_monthly": 3,
    "energy_cost_monthly": {
      "current": 158,
      "potential": 155
    },
    "energy_cost_yearly": {
      "current": 1896,
      "potential": 1864
    },
    "return_on_investment": "-0.89%",
    "loan": {
      "monthly_payment": 72
    }
  },
  "gas_usage": {
    "current": 741,
    "potential": 321
  },
  "electricity_usage": {
    "current": 2262,
    "potential": 4262
  },
  "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": "Goed",
        "value": 3,
        "points": 5
      },
      "after": {
        "desc": "Goed",
        "value": 3,
        "points": 5
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "floor_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Goed",
        "value": 3,
        "points": 7
      },
      "investment": 2553,
      "savings": 51,
      "co2_reduce": 67,
      "BENG2": "17",
      "gas_savings": 37,
      "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": "Dubbel glas",
        "value": 2,
        "points": 1
      },
      "after": {
        "desc": "Dubbel glas",
        "value": 2,
        "points": 1
      },
      "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": "Hybride WP",
        "value": 8,
        "points": 20
      },
      "investment": 6621,
      "savings": -38,
      "co2_reduce": -20,
      "BENG2": "80",
      "gas_savings": 368,
      "electricity_savings": -2000
    },
    "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": "Decentrale balansventilatie",
        "value": 4,
        "points": 5
      },
      "investment": 8226,
      "savings": 116,
      "co2_reduce": 152,
      "BENG2": "34",
      "gas_savings": 85,
      "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

{
  "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 house."
}

Request body

Example requests

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