be26 API Docs

What you can build

The API is for products that need calculation-grade energy numbers, not just a static registry lookup.

Energy label preview

Submit a building envelope, ventilation, lighting, hot-water, and heating-system model. Receive a BE26 energy label and compliance summary before a final certificate exists.

BE18 to BE26 comparison

Run equivalent inputs with standard: "BE18" and standard: "BE26" to compare old and new regulatory assumptions in an internal tool.

Address prefill

Resolve a typed Danish address into stable building identifiers, then use those identifiers to prefill area, construction year, usage, floors, wall material, roof material, and heat supply.

Existing label lookup

Fetch slim energy-label summaries for a building to compare a new design calculation with existing classification, heated area, emissions, savings, and improvement proposals.

Quickstart

Replace the placeholder host with your assigned API host. Keep the key server-side; do not ship it in browser code or mobile apps.

Environment

export BE26_BASE_URL="https://api.example.com"
read -rsp "BE26 API key: " BE26_API_KEY
echo

Calculate

curl -sS "$BE26_BASE_URL/v1/be26/calculate" \
  -H "Authorization: Bearer $BE26_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "standard": "BE26",
    "format": "json",
    "input": {
      "Building": {
        "Ae": 180,
        "Ae4": 180,
        "Dwellings": 1,
        "ThHeat": 21,
        "ThSetp": 23,
        "ThNV": 24,
        "ThCool": 25,
        "Tu": -12,
        "DimRoomTemp": 20,
        "HeatCap": 55,
        "UsageHoursPerWeek": 50,
        "StartTime": 8,
        "EndTime": 17,
        "BuildType": "Atype",
        "BasicHeatSupply": "SupEl",
        "CalcCondition": "Actual",
        "OpaqueConstr": [
          { "Area": 180, "U": 0.09, "B": 1 },
          { "Area": 156, "U": 0.08, "B": 1 },
          { "Area": 117.9, "U": 0.16, "B": 1 }
        ],
        "TranspConstr": [
          {
            "Area": 20,
            "U": 1,
            "B": 1,
            "Orient": "S",
            "Slope": 90,
            "G": 0.62,
            "FF": 0.75
          }
        ],
        "Ventilation": [
          {
            "Area": 180,
            "Fo": 1,
            "Qvm": 0.32,
            "Nvgv": 0.88,
            "Tin": 18,
            "Sel": 0.9
          }
        ],
        "Usage": {
          "Area": 180,
          "Load": { "Qp": 1.5, "Qe": 2.5, "QeNight": 1 }
        },
        "Lighting": {
          "Area": 180,
          "Load": {
            "PInst": 5,
            "EtaDim": 0.2,
            "Fo": 1,
            "RequiredLux": 300,
            "DaylightFactor": 2
          }
        },
        "HeatDistrib": { "InletTemp": 45, "ReturnTemp": 30 },
        "HotWater": { "Consumption": 250, "Temp": 55, "SupplyTemp": 60 }
      },
      "HeatingSystems": {
        "HeatPumps": [
          {
            "AFrac": 1,
            "VpType": "VpComb",
            "RoomHeating": {
              "NomEff": 5.2,
              "NomCOP": 4.2,
              "RelCOP50": 1,
              "TempCold": 2,
              "TempWarm": 30,
              "TypeCold": "VpU",
              "TypeWarm": "VpV"
            },
            "DHW": {
              "NomEff": 4.8,
              "NomCOP": 2.55,
              "RelCOP50": 1,
              "TempCold": 7,
              "TempWarm": 50,
              "TypeCold": "VpU",
              "TypeWarm": "VpV"
            }
          }
        ]
      }
    }
  }'

Success response

A successful calculation returns object: "be26.calculation", request_id, normalized input metadata, and a summary containing annual primary energy, label, compliance, heating, cooling, hot-water, electricity, and reference area fields.

Concrete examples

These examples show the type of output to expect. Exact values depend on your input model and the building selected.

1. Calculate a 180 m2 heat-pump building

Call: POST /v1/be26/calculate
Input: Envelope areas, U-values, ventilation, lighting, hot water, and heat pump parameters.
Output: A2015, 33.12 kWh/m2/year, compliant.

2. Resolve a Danish address

Call: GET /v1/buildings/resolve
Input: Vesterbrogade 1, 1620 Kobenhavn V
Output: Candidate IDs, display address, municipality, street, postal code, and coordinates.

3. Fetch building facts

Call: GET /v1/buildings/{id}/context
Input: An ID returned by address resolution.
Output: Construction year, usage, area, floors, materials, heat supply, property summary.

4. Compare with existing labels

Call: GET /v1/buildings/{id}/energy-labels
Input: A building or property identifier.
Output: Label class, validity period, heated area, energy need, emissions, savings, proposals.

Endpoints

The beta API surface is intentionally small. Use /v1/openapi.json on your assigned base URL as the source of truth for schemas.

GET

/v1/health

Basic service health.

GET

/v1/openapi.json

OpenAPI contract for the current public API surface.

GET

/v1/_describe

Compact route summary for agents and developer tools.

POST

/v1/be26/calculate

Calculate BE18 or BE26 from JSON input or raw BEXML.

GET

/v1/buildings/resolve

Resolve a Danish address query into candidate building identifiers.

GET

/v1/buildings/{id}/context

Fetch curated public building context for a resolved identifier.

GET

/v1/buildings/{id}/energy-labels

Fetch slim energy-label summaries for a resolved building.

Building lookup

curl -sS "$BE26_BASE_URL/v1/buildings/resolve?query=Vesterbrogade%201%2C%201620%20Kobenhavn%20V&limit=5" \
  -H "Authorization: Bearer $BE26_API_KEY"

Errors

Errors use application/problem+json. Preserve request_id when reporting failed or surprising responses.

Problem JSON

{
  "type": "https://docs.be26.dk/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request body failed validation.",
  "code": "validation_failed",
  "request_id": "req_...",
  "retryable": false,
  "errors": [
    {
      "field": "input.Building.Ae",
      "message": "must be greater than zero"
    }
  ]
}

Rate limits and retries

Responses can include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After. Retry only when an error response says retryable: true.