Getting Started

API Getting Started

This document contains a short tutorial on how the SkenData Approximation API works. The Approximation API is unidirectional, building data and results are returned for a building polygon or a living area. The API is stateless, a change to the building requires a new call with changed data. This API approximates a model building using the inputs provided via this API. The building does not exist in the real world. Results compared to a real building will differ as no additional geodata such as building heights are processed. Therefore, the results for this API should be used as an indication only.

This document should be used in conjunction with the OpenAPI spec (openapi.json). All endpoints and data schemas are specified there.

Get an Access-Token

We are using OpenID Connect with the Client Credentials Grant for retrieving an access token. Fill the environment variables CLIENT_ID and CLIENT_SECRET with the provided values.

export CLIENT_ID=XXXXXXXXXXXXXXXXXXX
export CLIENT_SECRET=XXXXXXXXXXXXXXXXXXX

curl -X 'POST' \
 'https://auth.grundsteuer.sken.dev/realms/skendata/protocol/openid-connect/token'   \
 -H 'accept: application/json'   \
 -H 'Content-Type: application/x-www-form-urlencoded'   \
 -d 'grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET'

You have to extract the access_token attribute value from the response and store it in the TOKEN environment variable.

Approximate a building

Approximate a building using only the living area. In this case, a model house is calculated and the output is only influenced by the living area input. The user should be shown visually which structural parameters this building has. If a building is only approximated via a living area, the building may have different numbers of stories or roof extensions.

# export TOKEN=XXXXXXXXXXXXXXXXXXX

curl -X 'POST' \
  'https://api.grundsteuer.sken.dev/v1/products/building_approximation' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "country_code": "de",
  "geometry": {
    "type": "living_area",
    "living_area": 110
  }
}'

Example Response

This output shows the calculated values that are generated just by specifying the living area. The full schema can be found in the openapi.json, some data has been truncated for this example.

{
  "building_type": "living",
  "building_construction": {
    "stories": 1,
    "roof_type": "pointed",
    "roof_development": "pointed_100_developed",
    "construction_year": 1995,
    ...
  },
  "building_energy": {
    "energy_efficiency_category": "e",
    "end_energy": {
      "area_related": 139.69116,
      "absolute": 22629.96724
    },
    "primary_energy": {
      "area_related": 156.84674,
      "absolute": 25409.17239
    },
    "co2_equivalent": {
      "area_related": 34.98255,
      "absolute": 5667.17314
    }
  },
  "building_energy_redevelopment_options": [
    ...
  ]
}

Detailed building data input

In this example, a building is described by its building polygon. Please note that initialization via polygons requires extra API client access roles. It is also configured as a mid-terrace house with 2 floors, a flat roof and no basement. The year of construction is set to 2005. The building has district heating with underfloor heating, the roof and windows were renovated in 2024.

# export TOKEN=XXXXXXXXXXXXXXXXXXX

curl -X 'POST' \
  'https://api.grundsteuer.sken.dev/v1/products/building_approximation' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "country_code": "de",
  "building_type": "living",
  "building_construction": {
    "stories": 2,
    "roof": {
      "roof_type": "flat",
      "roof_development": "undefined"
    },
    "cellar": {
      "cellar_existence": "unavailable",
      "cellar_development": "undefined",
      "cellar_location": "undefined"
    },
    "construction_year": 2005
  },
  "building_energy_information": {
    "main_energy_source": "district_heating_heating_plant_renewable_energies",
    "renovation_year_roof": 2024,
    "renovation_year_windows": 2024,
    "neighborhood_characteristic": "row_center",
    "heat_emitter": "floor_heating"
  },
  "geometry": {
    "type": "polygon",
    "polygon": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            12.1500689231,
            54.0852505047
          ],
          [
            12.1502510423,
            54.0851615036
          ],
          [
            12.1503151854,
            54.0852076962
          ],
          [
            12.1503875467,
            54.0852598058
          ],
          [
            12.1503013605,
            54.0853025197
          ],
          [
            12.1502079229,
            54.0853488406
          ],
          [
            12.1500689231,
            54.0852505047
          ]
        ]
      ]
    }
  }
}'