Authentication, input and response

Determine the estimated current or potential NTA 8800 energy label

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

Headers

Name	Type	Description
x-api-key*	string	Unique API Key from Altum. Create one via Mopsus(https://mopsus.altum.ai)
Content-Type	string	application/json

Request Body

Name	Type	Description
post_code*	String	1234AB
house_number*	Number	1
house_addition	String	A
inner_surface_area	Number	100
build_year	Number	2001
house_type	Number	current house-type: '2 onder 1 kap' = 1, 'hoekwoning' = 2, 'tussenwoning' = 3, 'vrijstaand' = 4 or 'appartment' = 5
installation	Number	current installation type - see measures
wall_insulation	Number	current wall insulation - see measures
roof_insulation	Number	current roof insulation - see measures
floor_insulation	Number	current floor insulation - see measures
living_room_windows	Number	current living room windows - see measures
bedroom_windows	Number	current bedroom windows - see measures
shower	Boolean	current shower WTW - see measures
ventilation	Number	current ventilation - see measures
solar_panels	Number	current solar panels in m2 ot total watt-peak capacity in W - see measures
solarpanel_watt_peak	Number	current solarpanel watt peak performance per m2
watt_panels	Boolean	assume solar_panels input is in W (0) or m2 (1). Default = 1
inhabitants	Integer	number of people living in the house

200: OK Successful response

{
	"Output": {
		"post_code": "2771DS",
		"house_number": 87,
		"house_addition": null,
		"build_year": 1961,
		"inner_surface_area": 151,
		"house_type": "vrijstaand",
		"installation": 4,
		"wall_insulation": 2,
		"roof_insulation": 2,
		"floor_insulation": 2,
		"living_room_windows": 2,
		"ventilation": 1,
		"bedroom_windows": 2,
		"shower": 0,
		"solar_panels": 15,
		"solarpanel_watt_peak": 300,
		"CO2": 3084,
		"definitive_energy_label": "C",
		"definitive_energy_label_type": "NEN7120",
		"definitive_energy_label_validity_date": "2030-12",
		"current_estimated_energy_label": "B",
		"current_estimated_BENG1_score": 146,
		"current_estimated_BENG2_score": 167,
		"estimated_gas_usage": 3108,
		"estimated_energy_usage": 760
	}
}

422: Unprocessable Entity Wrong input format

{
  "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 Unsuccessful response

{ 
    "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 Apartment error

{ 
    "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 Service is not available and/or down

{
	"message": "Internal server error"
}

404: Not Found If BagId is used instead of Address

{
     "detail": "Could not find any object with your BAG ID." 
}

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"
}

Determine the estimated current or potential NTA 8800 energy label

POST https://api.altum.ai/energylabel/bag

Use BAG_id as alternative to post_code, house_number and house_addition. All other inputs and outputs are similar.

Headers

Name	Type	Description
x-api-key*	string	API Key from Altum. Create one via Mopsus(https://mopsus.altum.ai)
Content-Type	string	application/json

Request Body

Name	Type	Description
bag_id*	string	16 digits BAG_ID
inner_surface_area	Number	100
build_year	Number	2001
house_type	Number	current house-type: '2 onder 1 kap' = 1, 'hoekwoning' = 2, 'tussenwoning' = 3, 'vrijstaand' = 4 or 'appartment' = 5
installation	Number	current installation type - see measures
wall_insulation	Number	current wall insulation - see measures
roof_insulation	Number	current roof insulation - see measures
floor_insulation	Number	current floor insulation - see measures
living_room_windows	Number	current living room windows - see measures
bedroom_windows	Number	current bedroom windows - see measures
shower	Boolean	current shower WTW - see measures
ventilation	Number	current ventilation - see measures
solar_panels	Number	current solar panels in m2 ot total watt-peak capacity in W - see measures
solarpanel_watt_peak	Number	current solarpanel watt peak performance per m2
watt_panels	Boolean	assume solar_panels input is in W (0) or m2 (1). Default = 1
inhabitants	Integer	number of people living in the house

200: OK Successful response

{
	"Output": {
		"post_code": "2771DS",
		"house_number": 87,
		"house_addition": null,
		"build_year": 1961,
		"inner_surface_area": 151,
		"house_type": "vrijstaand",
		"installation": 4,
		"wall_insulation": 2,
		"roof_insulation": 2,
		"floor_insulation": 2,
		"living_room_windows": 2,
		"ventilation": 1,
		"bedroom_windows": 2,
		"shower": 0,
		"solar_panels": 15,
		"solarpanel_watt_peak": 300,
		"CO2": 3084,
		"definitive_energy_label": "C",
		"definitive_energy_label_type": "NEN7120",
		"definitive_energy_label_validity_date": "2030-12",
		"current_estimated_energy_label": "B",
		"current_estimated_BENG2_score": 167,
		"estimated_gas_usage": 3108,
		"estimated_energy_usage": 760
	}
}

422: Unprocessable Entity Wrong input format

{
  "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 Unsuccessful response

{ 
    "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 Apartment error

{ 
    "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 Service is not available and/or down

{
	"message": "Internal server error"
}

404: Not Found If BagId is used instead of Address

{
     "detail": "Could not find any object with your BAG ID." 
}

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"
}

Request body

Example requests

{
  "post_code": "4709BM",
  "house_number": 1,
  "house_addition": "g",
  "installation": 1,
  "wall_insulation": 3,
  "roof_insulation": 2,
  "floor_insulation": 2,
  "living_room_windows": 3
}

{
  "bag_id": "0637010000264937",
  "installation": 1,
  "wall_insulation": 3,
  "roof_insulation": 2,
  "floor_insulation": 2,
  "living_room_windows": 3
}