{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/eliq/main/json-schema/eliq-result-wrapper-schema.json",
  "title": "Result wrapper",
  "description": "Responses from the similar homes and breakdown endpoint are wrapped in an object called result wrapper. The result status will contain information about the response and whether it is an ok or not ok result. The object also contains information of what needs to be done to get an ok response, for example enter more properties to the home profile.",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/eliq-breakdown-api-openapi.yml#/components/schemas/ResultWrapper",
  "type": "object",
  "properties": {
    "result": {
      "oneOf": [
        {
          "$ref": "#/$defs/Breakdown"
        },
        {
          "$ref": "#/$defs/SimilarHomesGroup"
        },
        {
          "$ref": "#/$defs/TimeseriesData"
        },
        {
          "$ref": "#/$defs/SimilarHomesReport"
        }
      ]
    },
    "result_status": {
      "type": "object",
      "description": "Contains information about the result, and whether it was successful or not",
      "required": [
        "code"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "description": "Either \"ok\" or \"not_ok\". Used to decide whether there is a result or not.",
          "enum": [
            "ok",
            "not_ok"
          ]
        },
        "action": {
          "type": [
            "object",
            "null"
          ],
          "description": "Available in cases where there are actions that can be done to make the result become ok, such as entering info in home profile options.",
          "properties": {
            "code": {
              "type": "string",
              "description": "A code for the action that should be taken. Please refer to documentation of specific endpoint for more information. "
            },
            "description": {
              "type": "string",
              "description": "A description of the action that should be taken."
            }
          }
        }
      }
    }
  },
  "required": [
    "result_status"
  ],
  "$defs": {
    "Breakdown": {
      "description": "The breakdown model contains information about the location breakdown (aka. Energy usage categories (EUC)). ",
      "type": "object",
      "title": "Breakdown result",
      "properties": {
        "accuracy": {
          "type": "string",
          "minLength": 1,
          "enum": [
            "LOW",
            "MEDIUM",
            "HIGH"
          ],
          "description": "How certain we are of the result. Can be either 'low', 'medium' or 'high'. Could be used to let user know the accuracy of the breakdown, or whether to show it the application or not."
        },
        "total_value": {
          "type": "number",
          "description": "The total usage during the period"
        },
        "from": {
          "type": "string",
          "minLength": 1,
          "format": "date-time",
          "description": "Start date of the consumption period, matches with the value passed in query parameters of the request."
        },
        "to": {
          "type": "string",
          "minLength": 1,
          "format": "date-time",
          "description": "End date of the consumption period, matches with the value passed in query parameters of the request.\n"
        },
        "unit": {
          "type": "string",
          "minLength": 1,
          "enum": [
            "energy",
            "cost"
          ],
          "description": "Can be ‘cost’ or ‘energy’. Matches with the value passed in query parameters of the request if provided, otherwise default."
        },
        "breakdown": {
          "type": "array",
          "uniqueItems": true,
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/BreakdownItem"
          }
        }
      },
      "required": [
        "accuracy",
        "total_value",
        "from",
        "to",
        "unit",
        "breakdown"
      ]
    },
    "BreakdownItem": {
      "description": "Breakdown item contain usage information for a specific usage category",
      "type": "object",
      "properties": {
        "category": {
          "type": "string",
          "minLength": 1,
          "description": "The breakdown category, eg. 'cooking' or 'always_on'"
        },
        "value": {
          "type": "number",
          "description": "The amount of usage for the category (either in energy or cost)"
        }
      },
      "required": [
        "category",
        "value"
      ]
    },
    "LimitRange": {
      "required": [
        "max",
        "min"
      ],
      "type": "object",
      "properties": {
        "min": {
          "type": "number",
          "description": "Minimum number in the range. For example, if key is 'living_area' and min is 150, it means minimum 150 square meters.",
          "format": "double"
        },
        "max": {
          "type": "number",
          "description": "Maximum number in the range. For example, if key is 'living_area' and max is 200, it means maximum 200 square meters.",
          "format": "double"
        }
      },
      "description": "Available if type is 'limit_range'. Contains minimum and maximum values for the given key."
    },
    "SimilarHomesGroup": {
      "required": [
        "contributors",
        "filters"
      ],
      "type": "object",
      "properties": {
        "filters": {
          "minItems": 1,
          "type": "array",
          "items": {
            "$ref": "#/$defs/SimilarHomesGroupFilter"
          },
          "description": "A list of filters that was used when finding a similar homes group."
        },
        "contributors": {
          "type": "integer",
          "description": "Number of contributors in the group.",
          "format": "int32"
        }
      },
      "description": "Description of similar homes that a location is compared to."
    },
    "SimilarHomesGroupFilter": {
      "required": [
        "description",
        "key",
        "type"
      ],
      "type": "object",
      "properties": {
        "key": {
          "minLength": 1,
          "type": "string",
          "description": "This key refers to keys in home profile, for example 'house_type', 'heating_type_primary' or 'living_area'."
        },
        "description": {
          "minLength": 1,
          "type": "string",
          "description": "Description for the filter."
        },
        "type": {
          "$ref": "#/$defs/SimilarHomesGroupFilterType"
        },
        "limit_range": {
          "$ref": "#/$defs/LimitRange"
        },
        "limit_values": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Available if type is 'limit_values'. For example, for key 'house_type', this would include the list of house types the location is compared with."
        }
      },
      "description": "Similar homes group filter."
    },
    "SimilarHomesGroupFilterType": {
      "enum": [
        "limit_values",
        "limit_range"
      ],
      "type": "string",
      "description": "Describes whether 'limit_values' or 'limit_range' should be used."
    },
    "SimilarHomesReport": {
      "required": [
        "distribution_values",
        "from",
        "to",
        "value"
      ],
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "description": "Average energy in Wh or cost for similar homes over the requested period",
          "format": "double"
        },
        "distribution_values": {
          "type": "array",
          "items": {
            "type": "number",
            "format": "double"
          },
          "description": "Similar homes consumption data deciles. Contains values for all 10 ranks of deciles - starting from 1st and ending with 10th decile. The 1st decile has 10 per cent of the data set below it, the 2nd decile has 20 per cent of the data set below and so on. The 10th decile has 100 per cent of the data set below, making it a maximum value for the dataset."
        },
        "energy_wh": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Average energy Wh for similar homes over the requested period",
          "format": "int32",
          "deprecated": true
        },
        "distribution": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer",
            "format": "int32"
          },
          "description": "Distribution of similar homes energy Wh consumption in deciles",
          "deprecated": true
        },
        "from": {
          "type": "string",
          "description": "From date",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "description": "To date",
          "format": "date-time"
        }
      },
      "description": "Similar homes report for the requested period."
    },
    "TimeseriesData": {
      "description": "Model containing time series data. Different parameters will be available depending on the data requested, see below for more information",
      "type": "object",
      "title": "Time series data",
      "properties": {
        "consumption": {
          "type": "array",
          "description": "Available if consumption has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The consumption values are floating-point numbers.",
          "items": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "import": {
          "type": "array",
          "description": "Available if import has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The import values are floating-point numbers.",
          "items": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "export": {
          "type": "array",
          "description": "Available if export has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The export values are floating-point numbers.",
          "items": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "production": {
          "type": "array",
          "description": "Available if production has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists (One day always contains 24 values). The production values are floating-point numbers.",
          "items": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "forecast": {
          "type": "array",
          "description": "Available if forecast has been queried. Will always contain the exact amount of elements as there are time frames between ‘to’ and ‘from’ with the given ‘resolution’. Values inside the array can be null if no energy data exists. The forecast values are floating-point numbers.",
          "items": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "fuel": {
          "type": "string",
          "minLength": 1,
          "description": "Can be ‘elec’, ‘gas’ or ‘district_heating’. Matches with the value passed in query parameters of the request if provided",
          "enum": [
            "elec",
            "gas",
            "district_heating"
          ]
        },
        "unit": {
          "type": "string",
          "minLength": 1,
          "description": "Can be ‘cost’, ‘energy’ or 'm3'. Matches with the value passed in query parameters of the request if provided, otherwise default.\n\nOnly return m3 if the unit is available.",
          "enum": [
            "energy",
            "cost"
          ]
        },
        "resolution": {
          "type": "string",
          "minLength": 1,
          "description": "Can be '6min','15min', '30min', 'hour', 'day' or 'month'. Matches with the value passed in query parameters of the request.",
          "enum": [
            "6min",
            "15min",
            "30min",
            "hour",
            "day",
            "month"
          ]
        },
        "from": {
          "type": "string",
          "minLength": 1,
          "description": "From date"
        },
        "to": {
          "type": "string",
          "minLength": 1,
          "description": "To date"
        }
      },
      "required": [
        "fuel",
        "unit",
        "resolution",
        "from",
        "to"
      ]
    }
  }
}