{
  "openapi": "3.1.0",
  "info": {
    "title": "Soljo Data API",
    "version": "1.0.0",
    "description": "Building energy profiles for Swiss addresses from official data: roof faces (Sonnendach, BFE), building facts (federal building register GWR), measured shading (swisstopo LiDAR), yield (PVGIS), turnkey cost (BFE price study), subsidies (Pronovo), local electricity price (ElCom) and feed-in tariff, plus savings, payback and 25-year net result. Same calculation as the Soljo report. Every value block lists sourceIds that resolve to the sources array. Estimates, not offers and not official extracts.",
    "contact": {
      "url": "https://soljo.ch/developers"
    },
    "termsOfService": "https://soljo.ch/developers#terms"
  },
  "servers": [
    {
      "url": "https://cwghnqlpeeocjsjfhgyk.supabase.co/functions/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Free key with 100 profiles per month: https://soljo.ch/developers. Without a key a small anonymous allowance applies (5 per day)."
      }
    }
  },
  "security": [
    {
      "apiKey": []
    },
    {}
  ],
  "paths": {
    "/building-profile": {
      "post": {
        "operationId": "buildingProfile",
        "summary": "Building energy profile for a Swiss address",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 200,
                    "example": "Bundesplatz 3, 3011 Bern",
                    "description": "Swiss street address with house number and postcode."
                  },
                  "household_size": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 3
                  },
                  "annual_consumption_kwh": {
                    "type": "number",
                    "minimum": 500,
                    "maximum": 100000,
                    "description": "Overrides household_size."
                  },
                  "battery": {
                    "type": "boolean",
                    "default": false
                  },
                  "heat_pump": {
                    "type": "boolean",
                    "default": false
                  },
                  "ev": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile",
            "headers": {
              "X-Quota-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Quota-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-Plan": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "example": {
                  "type": "soljo_building_profile",
                  "version": 1,
                  "generatedAt": "2026-10-27T20:00:00.000Z",
                  "location": {
                    "label": "Bundesplatz 3, 3011 Bern",
                    "lat": 46.946773529052734,
                    "lon": 7.444191932678223,
                    "postcode": "3011",
                    "municipality": "Bern",
                    "canton": "BE",
                    "bfsNr": 3,
                    "egid": 2242547,
                    "country": "CH"
                  },
                  "building": {
                    "egid": 2242547,
                    "egrid": "CH294676423526",
                    "category": "non_residential",
                    "constructionYear": null,
                    "constructionPeriod": null,
                    "floors": null,
                    "footprintM2": 3697,
                    "dwellings": null,
                    "heating": {
                      "energySource": "district_heating",
                      "heatPump": false,
                      "updated": "2024-12-10"
                    },
                    "hotWater": {
                      "energySource": "district_heating"
                    },
                    "codes": {
                      "gkat": 1060,
                      "gbaup": null,
                      "genh1": 7580,
                      "gwaerzh1": 7460,
                      "genw1": 7580
                    },
                    "exportDate": "2026-10-25"
                  },
                  "roof": {
                    "faces": [
                      {
                        "id": "14664870",
                        "areaM2": 245.3,
                        "tiltDeg": 20,
                        "azimuthDeg": 264,
                        "suitability": "medium",
                        "irradiationKwhM2": 943
                      }
                    ],
                    "areaM2": 245,
                    "roofType": "pitched",
                    "azimuthConvention": "compass: 0 = north, 90 = east, 180 = south, 270 = west",
                    "sourceIds": [
                      "roof"
                    ]
                  },
                  "shading": {
                    "lossPct": 24.9,
                    "winterLossPct": 33.8,
                    "summerLossPct": 21.4,
                    "usableRoofSharePct": 73,
                    "method": "Ray tracing on the 0.5 m LiDAR surface model (buildings, trees, roof objects); distant terrain is in the irradiance data",
                    "sourceIds": [
                      "shading"
                    ]
                  },
                  "system": {
                    "panels": 75,
                    "kwp": 33.8,
                    "annualProductionKwh": 32352,
                    "specificYieldKwhPerKwp": 957,
                    "productionSource": "measured",
                    "co2SavedKgPerYear": 4206,
                    "sourceIds": [
                      "irradiance",
                      "shading"
                    ]
                  },
                  "economics": {
                    "currency": "CHF",
                    "investment": 65189,
                    "federalSubsidy": 11940,
                    "cantonalSubsidy": 1200,
                    "netInvestment": 52049,
                    "electricityPricePerKwh": 0.3567,
                    "feedInPerKwh": 0.0759,
                    "selfConsumptionPct": 5,
                    "annualConsumptionKwh": 3380,
                    "annualSavings": 2947,
                    "paybackYears": 17.7,
                    "rating": "tight",
                    "netResult25Years": 12270,
                    "netResult25YearsPriceScenarios": {
                      "mid": 15184,
                      "high": 18855
                    },
                    "assumptions": {
                      "householdSize": 3,
                      "battery": false,
                      "heatPump": false,
                      "ev": false,
                      "electricityPrice": "today's price for the whole period; scenarios only on self-consumed electricity",
                      "prices": "incl. 8.1 % VAT"
                    },
                    "sourceIds": [
                      "electricity_price",
                      "investment",
                      "subsidy",
                      "feed_in"
                    ]
                  },
                  "sources": [
                    {
                      "id": "address",
                      "title": "Amtliches Gebäudeadressverzeichnis, swisstopo",
                      "url": "https://www.swisstopo.admin.ch"
                    },
                    {
                      "id": "roof",
                      "title": "Sonnendach.ch, Bundesamt für Energie (BFE)",
                      "url": "https://www.sonnendach.ch"
                    },
                    {
                      "id": "building",
                      "title": "Eidg. Gebäude- und Wohnungsregister (GWR), BFS",
                      "url": "https://www.housing-stat.ch",
                      "date": "2026-10-25"
                    },
                    {
                      "id": "shading",
                      "title": "swissSURFACE3D (LiDAR), swisstopo; Soljo shading model",
                      "url": "https://www.swisstopo.admin.ch/de/hoehenmodell-swisssurface3d-raster",
                      "date": "2023"
                    },
                    {
                      "id": "irradiance",
                      "title": "PVGIS 5.3, European Commission JRC",
                      "url": "https://re.jrc.ec.europa.eu/pvg_tools/"
                    },
                    {
                      "id": "electricity_price",
                      "title": "ElCom electricity tariffs 2026, Bern",
                      "url": "https://www.strompreis.elcom.admin.ch"
                    },
                    {
                      "id": "investment",
                      "title": "Preisbeobachtungsstudie Photovoltaik 2025, EnergieSchweiz/BFE",
                      "url": "https://pubdb.bfe.admin.ch/de/publication/download/12694"
                    },
                    {
                      "id": "subsidy",
                      "title": "Einmalvergütung (EIV), Pronovo",
                      "url": "https://pronovo.ch/de/services/tarifrechner/"
                    },
                    {
                      "id": "feed_in",
                      "title": "Energieverordnung Art. 12 and BFE reference market price",
                      "url": "https://www.fedlex.admin.ch/eli/cc/2017/763/de"
                    }
                  ],
                  "notes": [
                    "Estimate based on official data and the Soljo model; not an offer and not an official extract.",
                    "Values are rounded; check the roof on site before ordering a system."
                  ],
                  "reportUrl": "https://soljo.ch/?adresse=Bundesplatz%203%2C%203011%20Bern"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unknown or revoked API key"
          },
          "404": {
            "description": "Address not found (Swiss addresses only)"
          },
          "422": {
            "description": "No roof data for this address"
          },
          "429": {
            "description": "Quota used up"
          },
          "502": {
            "description": "A data source did not respond; retry"
          }
        }
      }
    }
  }
}