Authentication, input and response

Request a sustainability advice based on address.

POST 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

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

Field

Type

Description

Example/Default

postcode*

string

Six-character postcode format

1234AB

housenumber*

integer

House number of the object

houseaddition

string

Addition to the house number

build_year

integer

Year the object was built

1956

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

inner_surface_area

float

inner surface area (m2)

wall_insulation

integer

see Measures

floor_insulation

integer

see Measures

sloped_roof_insulation

integer

see Measures

flat_roof_insulation

integer

see Measures

living_room_windows

integer

see Measures

bedroom_windows

integer

see Measures

installation

integer

see Measures

Default: 4

shower

integer

see Measures

Default: 1

ventilation

integer

see Measures

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

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 (m3)

1000

heat_usage

float

Overwrites specified yearly heat consumption (GJ)

electricity_usage

float

Overwrites specified yearly electricity consumption (kWh)

2600

electricity_generation

float

Total yearly electricity yield of solar panels in kWh.

Net usage = consumption - yield

800

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

battery_type

integer

see Measures

battery_system

integer

see Measures

minimum_solar_panels

integer

The minimum number of new panels to be placed

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

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

sloped_roof_filters

dict

see Measure filters

flat_roof_filters

dict

see Measure filters

floor_filters

dict

see Measure filters

energylabel_strict

integer

enable strict search of results within target_label with 1

Default: 0

eco_delta

integer

Fetching ecovalue

0 = Disable

1 = Enable

Default: 1

lock_measures

list

see Lock measures

exclude_measures

list

see Exclude measures

{
  "warnings": [
    {
      "code": "11",
      "description": "Current building with energy label A++ already meets default target_label A+."
    }
  ],
  "address": {
    "housenumber": 87,
    "postcode": "2771DS",
    "houseaddition": null,
    "street": "Zuidkade",
    "city": "Boskoop",
    "location": {
      "lat": 52.0683938167,
      "lon": 4.6580852695
    }
  },
  "building": {
    "build_year": 1961,
    "inner_surface": 131,
    "floor_surface": 80.8,
    "flat_roof_surface": 5.2,
    "pitched_roof_surface": 98.9,
    "wall_surface": 126.1,
    "glass_living_room_surface": 11.1,
    "glass_bedrooms_surface": 16.6,
    "number_of_doors": 6,
    "type": "Vrijstaand"
  },
  "label": {
    "current": "A++",
    "potential": "A++"
  },
  "accuracy_indicator": 6,
  "provided_label": {
    "temporary": "F",
    "definitive": "A+++",
    "definitive_type": "NTA 8800:2024 (basisopname woningbouw)",
    "definitive_validity": "2036-1",
    "definitive_beng2": 49
  },
  "BENG2": {
    "current": 75,
    "potential": 58
  },
  "meta": null,
  "CO2": {
    "current": 3607,
    "potential": 1860
  },
  "grid_import": {
    "current": 10609,
    "potential": 9025
  },
  "grid_feed": {
    "current": 0,
    "potential": 0
  },
  "electricity_need": {
    "current": 10609,
    "potential": 9025
  },
  "financial": {
    "total_investment": 2257,
    "total_saving": 427,
    "months_to_pay_off": 63,
    "eco_value": 0,
    "savings_monthly": 36,
    "energy_cost_monthly": {
      "current": 234,
      "potential": 198
    },
    "energy_cost_yearly": {
      "current": 2803,
      "potential": 2376
    },
    "electricity_cost_yearly": {
      "current": 3439,
      "potential": 3011
    },
    "return_on_investment": "49.35%",
    "loan": {
      "monthly_payment": 9
    }
  },
  "gas_usage": {
    "current": 0,
    "potential": 0
  },
  "electricity_usage": {
    "current": 10613,
    "potential": 10613
  },
  "city_heating_usage": {
    "current": 0,
    "potential": 0
  },
  "energy_prices": {
    "variable_gas_price": 1.359,
    "variable_electricity_price": 0.27,
    "solarpanel_watt_peak_per_m2": 250
  },
  "solar_panels": {
    "summary": {
      "current": {
        "pv_generation": 0,
        "curtailed_pv": 0,
        "self_consumed_pv": 0,
        "self_consumed_ratio": 0,
        "netting_enabled": 1
      },
      "potential": {
        "pv_generation": 1584,
        "curtailed_pv": 0,
        "self_consumed_pv": 1584,
        "self_consumed_ratio": 1,
        "netting_enabled": 1
      }
    },
    "systems": {
      "current": null,
      "potential": [
        {
          "roof_surface": 0,
          "roof_type": "sloped",
          "original_watt_peak_capacity": null,
          "total_watt_peak_capacity": null,
          "inclination_angle": 45,
          "orientation": 180,
          "added_watt_peak_capacity": 1650,
          "specific_watt_peak_of_added_panels": null,
          "added_panels": 4,
          "panel_size": null
        }
      ]
    }
  },
  "battery": {
    "current": [
      {
        "type": "plug_in",
        "capacity": 6,
        "power": 2,
        "control_mode": "pv_only",
        "charge": 0,
        "discharge": 4,
        "cycles": 0.7
      }
    ],
    "potential": [
      {
        "type": "plug_in",
        "capacity": 6,
        "power": 2,
        "control_mode": "pv_only",
        "charge": 4,
        "discharge": 7,
        "cycles": 1.3
      }
    ]
  },
  "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": "Goed",
        "value": 3,
        "points": 7
      },
      "after": {
        "desc": "Goed",
        "value": 3,
        "points": 7
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "sloped_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
    },
    "flat_roof_insulation": {
      "before": {
        "desc": "Geen",
        "value": 1,
        "points": 0
      },
      "after": {
        "desc": "Goed",
        "value": 3,
        "points": 3
      },
      "investment": 484,
      "savings": 990,
      "co2_reduce": 1248,
      "BENG2": "2",
      "gas_savings": 0,
      "electricity_savings": 3675
    },
    "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
    },
    "bedroom_windows": {
      "before": {
        "desc": "Dubbel glas",
        "value": 2,
        "points": null
      },
      "after": {
        "desc": "Dubbel glas",
        "value": 2,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "installation": {
      "before": {
        "desc": "Elektrishe lucht-water WP",
        "value": 6,
        "points": 15
      },
      "after": {
        "desc": "Elektrishe lucht-water WP",
        "value": 6,
        "points": 15
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "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": "Decentrale balansventilatie",
        "value": 4,
        "points": 5
      },
      "after": {
        "desc": "Decentrale balansventilatie",
        "value": 4,
        "points": 5
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    },
    "solar_panels": {
      "before": {
        "desc": "0",
        "value": 0,
        "points": null
      },
      "after": {
        "desc": "4",
        "value": 4,
        "points": null
      },
      "investment": 1772,
      "savings": 276,
      "co2_reduce": 498,
      "BENG2": "97",
      "gas_savings": 0,
      "electricity_savings": 1466
    },
    "electric_cooking": {
      "before": {
        "desc": "Electric stove",
        "value": 2,
        "points": null
      },
      "after": {
        "desc": "Electric stove",
        "value": 2,
        "points": null
      },
      "investment": 0,
      "savings": 0,
      "co2_reduce": 0,
      "BENG2": "0",
      "gas_savings": 0,
      "electricity_savings": 0
    }
  },
  "response_meta": null
}

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

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

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

{
	"message": "Internal server error"
}

{
	"message": "Missing Authentication Token"
}

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

{ 
  "detail": "House type not found in database. Use house_type parameter instead." 
}

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

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

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

{
	"message": "Internal server error"
}

{
	"message": "Missing Authentication Token"
}

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

{ 
  "detail": "House type not found in database. Use house_type parameter instead." 
}

Request body

Example requests

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

VorigeChangelog VolgendeAPI Key Information

Laatst bijgewerkt 2 dagen geleden