Authentication, input and response

Determine the estimated current or potential NTA 8800 energy label

POST https://api.altum.ai/v2/energylabel/houses

Headers

Name	Type	Description
x-api-key*	string	Unique API Key from Altum. Create one on https://platform.altum.ai
Content-Type	string	application/json

Request Body

Field	Type	Description	Example/Default
postcode*	string	zip code in six-character format	1234AB
housenumber*	integer	house number	1
houseaddition	string	addition to the house number	A
build_year	integer	build year	1960
roof_type	integer	1 = (mostly) sloped roof 2 = (mostly) flat roof 3 = part sloped, part flat roof If either flat or sloped is > 25% it is type 3	Default: 1
house_type	integer	1 = Vrijstaand 2 = 2 onder 1 kap 3 = Hoekwoning 4 = Tussenwoning	2
inner_surface_area	float	inner surface area (m2)	70
wall_insulation	integer	see Measures	2
floor_insulation	integer	see Measures	2
sloped_roof_insulation	integer	see Measures	2
flat_roof_insulation	integer	see Measures	2
living_room_windows	integer	see Measures	2
bedroom_windows	integer	see Measures	2
installation	integer	see Measures	Default: 4
shower	integer	see Measures	Default: 1
cooling	integer	Is there a cooling system present? 1 = No cooling 2 = Air conditioning unit, direct air cooling	Default: 1
ventilation	integer	see Measures	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
ev_charger	integer	Does the building have a EV charger? 0 = no charger 1 = EV charger	Default: 0
electricity_connection_type	integer	The connection type of the building 1 = 1-phase 2 = 3-phase	Default: 1
electricity_contract_type	integer	Electricity contract type 1 = fixed contract 2 = dynamic contract	Default: 1
dynamic_price_reference_year	integer	The year from where the dynamic prices are used: 2023, 2024, 2025	Default: 2025
netting_enabled	integer	Whether the netting ruling (salderingsregeling) is applied 0 = No netting 1 = Netting applied	Default: 1
solar_panels	list	see Measures
number_of_solar_panels	integer	see Measures
battery_type	integer	see Measures
battery_system	integer	see Measures

Request body

{
  "postcode": "2771DS",
  "housenumber": 87,
  "houseaddition": ""
}

Response Status Codes

200: OK Successful response

{
  "Output": {
    "warnings": [],
    "postcode": "2771DS",
    "housenumber": 87,
    "houseaddition": null,
    "build_year": 1961,
    "inner_surface_area": 131,
    "house_type": "Vrijstaand",
    "installation": 6,
    "wall_insulation": 3,
    "sloped_roof_insulation": 1,
    "flat_roof_insulation": 1,
    "floor_insulation": 3,
    "living_room_windows": 2,
    "bedroom_windows": 2,
    "shower": 1,
    "ventilation": 4,
    "cooling": 1,
    "electric_cooking": 2,
    "solar_panels": {
      "pv_generation": 0,
      "curtailed_pv": 0,
      "self_consumed_pv": 0,
      "self_consumed_ratio": 0,
      "netting_enabled": 1
    },
    "battery": null,
    "CO2": 2299,
    "grid_import": 10436,
    "grid_feed": 0,
    "electricity_need": 10436,
    "definitive_energy_label": "A+++",
    "definitive_energy_label_type": "NTA 8800:2024 (basisopname woningbouw)",
    "definitive_energy_label_validity_date": "2036-1",
    "definitive_BENG2_score": 49,
    "current_estimated_energy_label": "A++",
    "current_estimated_BENG2_score": 75,
    "estimated_gas_usage": 0,
    "estimated_energy_usage": 10438,
    "estimated_city_heating_usage": 0,
    "measures_method": 1,
    "accuracy_indicator": 6,
    "response_meta": null
  }
}

422: Unprocessable Entity

{
  "detail": [
    {
      "loc": [
        "body",
        "postcode"
      ],
      "msg": "string does not match regex \"^(?!1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|1010)[1-9][0-9]{3}[A-Z]{2}$\"",
      "type": "value_error.str.regex",
      "ctx": {
        "pattern": "^(?!1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|1010)[1-9][0-9]{3}[A-Z]{2}$"
      }
    }
  ]
}

400: Bad Request

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

{
     "detail": "No measures suggested for this combination of input."
}

{
     "detail": "Code used in exclude_measure parameter is invalid"
}

{
     "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": "Gevelisolatie code ongeldig"
}

301: Moved Permanently

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

303: See Other House-type error

{ 
    "detail": "The house type of the given house was not found in database. Use house_type parameter instead."
}

500: Internal Server Error

{
	"message": "Internal server error"
}

401: Unauthorized No access

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

403: Forbidden Forbidden

{
	"message": "Missing Authentication Token"
}