{
  "openapi": "3.1.0",
  "info": {
    "title": "iONE Decision Engine",
    "version": "1.0.0",
    "summary": "Decides what to do about the heating of a European building, with reasons, alternatives and what is still missing.",
    "description": "Call this when someone asks whether to replace a boiler, whether a heat pump makes sense for their house, how large a heat pump or battery they need, or what heating would cost per month after a change. The answer is a decision with its reasons, three alternatives that were each actually computed, the equipment of the recommended one, the monthly budget against what the household pays today, and — the field to act on — missingInformation: the questions still worth asking, each with how much the answer would move the figure. Ask one of them, call again with it, and the answer narrows. Every figure carries its source. It is an estimate, never a quotation.",
    "contact": {
      "name": "G.T. GmbH",
      "url": "https://ione.energy"
    }
  },
  "servers": [
    {
      "url": "https://ione.energy"
    }
  ],
  "paths": {
    "/v1/decide": {
      "get": {
        "operationId": "decideFromQuery",
        "summary": "Decide, from query parameters (citable, cacheable).",
        "description": "The same decision as the POST form, taken from query parameters. Use this when the result should be linkable — an answer given to a person can carry the URL, and the person can open it. Any parameter may be omitted; what is omitted is assumed, and every assumption comes back in missingInformation with the spread it would close.",
        "parameters": [
          {
            "name": "postcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "houseType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "detached",
                "semi",
                "terraced",
                "apartment"
              ]
            }
          },
          {
            "name": "floorArea",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 20,
              "maximum": 2000
            }
          },
          {
            "name": "constructionEra",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pre1979",
                "1979_1994",
                "1995_2009",
                "post2010"
              ]
            }
          },
          {
            "name": "insulation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "original",
                "partly",
                "good",
                "new"
              ]
            }
          },
          {
            "name": "currentHeating",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "gas",
                "gas_old",
                "oil",
                "electric",
                "pellets",
                "coal",
                "heatpump"
              ]
            }
          },
          {
            "name": "existingEmitters",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "underfloor",
                "radiators",
                "fancoils",
                "mixed"
              ]
            }
          },
          {
            "name": "emitterPlan",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "keep",
                "fancoils"
              ]
            }
          },
          {
            "name": "solarPv",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no",
                "planned"
              ]
            }
          },
          {
            "name": "currentMonthlySpend",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 5000
            }
          },
          {
            "name": "installationIncluded",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ownerOccupied",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "incomeUnder40k",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no",
                "unknown"
              ]
            }
          },
          {
            "name": "roofShape",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "single",
                "gable",
                "hip",
                "flat"
              ]
            }
          },
          {
            "name": "roofAspect",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "south",
                "south_east",
                "south_west",
                "east",
                "west",
                "north",
                "flat"
              ]
            }
          },
          {
            "name": "roofPitch",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "flat",
                "shallow",
                "standard",
                "steep"
              ]
            }
          },
          {
            "name": "buildingLength",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 200
            }
          },
          {
            "name": "buildingWidth",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 200
            }
          },
          {
            "name": "panelCount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A decision, its reasons, the alternatives, and what is still missing.",
            "content": {
              "application/json": {}
            }
          },
          "400": {
            "description": "A parameter could not be used; nothing was calculated."
          }
        }
      },
      "post": {
        "operationId": "decide",
        "summary": "Decide what to do about a building.",
        "description": "The canonical call. Send whatever is known about the building; every field is optional. The response is a decision, its reasons, the computed alternatives, the recommended option with its equipment and economics, what is still missing and what each missing answer would change, and the source of every figure.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postcode": {
                    "type": "string"
                  },
                  "houseType": {
                    "type": "string",
                    "enum": [
                      "detached",
                      "semi",
                      "terraced",
                      "apartment"
                    ]
                  },
                  "floorArea": {
                    "type": "number",
                    "minimum": 20,
                    "maximum": 2000
                  },
                  "constructionEra": {
                    "type": "string",
                    "enum": [
                      "pre1979",
                      "1979_1994",
                      "1995_2009",
                      "post2010"
                    ]
                  },
                  "insulation": {
                    "type": "string",
                    "enum": [
                      "original",
                      "partly",
                      "good",
                      "new"
                    ]
                  },
                  "currentHeating": {
                    "type": "string",
                    "enum": [
                      "gas",
                      "gas_old",
                      "oil",
                      "electric",
                      "pellets",
                      "coal",
                      "heatpump"
                    ]
                  },
                  "existingEmitters": {
                    "type": "string",
                    "enum": [
                      "underfloor",
                      "radiators",
                      "fancoils",
                      "mixed"
                    ]
                  },
                  "emitterPlan": {
                    "type": "string",
                    "enum": [
                      "keep",
                      "fancoils"
                    ]
                  },
                  "solarPv": {
                    "type": "string",
                    "enum": [
                      "yes",
                      "no",
                      "planned"
                    ]
                  },
                  "currentMonthlySpend": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "installationIncluded": {
                    "type": "boolean"
                  },
                  "ownerOccupied": {
                    "type": "boolean"
                  },
                  "incomeUnder40k": {
                    "type": "string",
                    "enum": [
                      "yes",
                      "no",
                      "unknown"
                    ]
                  },
                  "roofShape": {
                    "type": "string",
                    "enum": [
                      "single",
                      "gable",
                      "hip",
                      "flat"
                    ]
                  },
                  "roofAspect": {
                    "type": "string",
                    "enum": [
                      "south",
                      "south_east",
                      "south_west",
                      "east",
                      "west",
                      "north",
                      "flat"
                    ]
                  },
                  "roofPitch": {
                    "type": "string",
                    "enum": [
                      "flat",
                      "shallow",
                      "standard",
                      "steep"
                    ]
                  },
                  "buildingLength": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 200
                  },
                  "buildingWidth": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 200
                  },
                  "panelCount": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 200
                  }
                }
              },
              "example": {
                "postcode": "80331",
                "floorArea": 160,
                "constructionEra": "pre1979",
                "insulation": "original",
                "currentHeating": "gas_old",
                "existingEmitters": "radiators",
                "solarPv": "planned",
                "roofShape": "gable",
                "roofAspect": "south",
                "buildingLength": 12,
                "buildingWidth": 9
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A decision, its reasons, the alternatives, and what is still missing.",
            "content": {
              "application/json": {}
            }
          },
          "400": {
            "description": "A parameter could not be used; nothing was calculated."
          }
        }
      }
    }
  }
}