{
 "openapi": "3.1.0",
 "info": {
  "title": "Alva Energy and Solar API",
  "version": "1.0.0",
  "description": "Irish household energy prices for AI agents and developers. Electricity, gas and dual-fuel tariffs for the Republic of Ireland and Northern Ireland, collected from supplier websites (and, for a few Northern Ireland suppliers, the Consumer Council NI comparison table). Every published value is agreed by independent extractors and grounded in the source document; `verification.level` says which check passed. Costs are estimates including VAT. Solar PV (Republic of Ireland): estimates from PVGIS data with SEAI grants, installers from the SEAI register, and package prices installers publish on their own websites (each figure checked against the page). Also available as an MCP server (streamable HTTP) at /mcp. Free, no key needed; please cache responses.",
  "contact": {
   "name": "Alva",
   "url": "https://www.alvacompare.com"
  }
 },
 "servers": [
  {
   "url": "https://api.alvacompare.com"
  },
  {
   "url": "https://www.alvacompare.com"
  }
 ],
 "paths": {
  "/v1/energy/suppliers": {
   "get": {
    "operationId": "listSuppliers",
    "summary": "Suppliers covered",
    "parameters": [
     {
      "name": "market",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "roi",
        "ni"
       ],
       "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Suppliers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data_as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this data was last refreshed (daily)"
          },
          "suppliers": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Supplier"
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/energy/tariffs": {
   "get": {
    "operationId": "listTariffs",
    "summary": "Live tariffs",
    "parameters": [
     {
      "name": "market",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "roi",
        "ni"
       ],
       "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)"
      }
     },
     {
      "name": "fuel",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "electricity",
        "gas",
        "dual"
       ]
      }
     },
     {
      "name": "meter_type",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "24h",
        "day_night",
        "smart_tou",
        "ev",
        "gas"
       ]
      }
     },
     {
      "name": "supplier",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "detail",
      "in": "query",
      "schema": {
       "type": "boolean",
       "default": false
      },
      "description": "Include every rate component"
     }
    ],
    "responses": {
     "200": {
      "description": "Tariffs",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data_as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this data was last refreshed (daily)"
          },
          "count": {
           "type": "integer"
          },
          "tariffs": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Tariff"
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/energy/tariffs/{tariff_id}": {
   "get": {
    "operationId": "getTariff",
    "summary": "One tariff with full rates",
    "description": "Tariff ids contain slashes (supplier/fuel/meter/...); use them as-is in the path.",
    "parameters": [
     {
      "name": "tariff_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Tariff",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Tariff"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/v1/energy/quote": {
   "post": {
    "operationId": "quote",
    "summary": "Rank tariffs by estimated annual cost",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "market": {
          "type": "string",
          "enum": [
           "roi",
           "ni"
          ],
          "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)",
          "default": "roi"
         },
         "fuel": {
          "type": "string",
          "enum": [
           "electricity",
           "gas",
           "dual"
          ],
          "default": "electricity"
         },
         "meter": {
          "type": "string",
          "enum": [
           "24h",
           "day_night",
           "smart"
          ],
          "default": "24h",
          "description": "The household's meter"
         },
         "region": {
          "type": "string",
          "enum": [
           "urban",
           "rural"
          ],
          "default": "urban"
         },
         "electricity_kwh": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 200000,
          "description": "Annual kWh; default typical usage (ROI 4,200, NI 3,200)"
         },
         "gas_kwh": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 500000,
          "description": "Annual kWh; default typical usage (ROI 11,000, NI 12,000)"
         },
         "night_share": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Share of electricity used 23:00-08:00, for day/night meters (default 0.4) and smart meters (default 0.39)"
         },
         "peak_share": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Smart meters: share used 17:00-19:00 (default 0.09)"
         },
         "weekend_share": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Smart meters: share used on Saturday and Sunday (default 2/7)"
         },
         "one_per_supplier": {
          "type": "boolean",
          "default": false,
          "description": "Keep only each supplier's cheapest tariff"
         },
         "tag": {
          "type": "string",
          "enum": [
           "fixed_price",
           "discount",
           "cashback",
           "ev_owners",
           "weekend_rates",
           "free_period",
           "time_of_use",
           "pay_as_you_go"
          ],
          "description": "Rank only tariffs with this tag, e.g. weekend_rates or fixed_price"
         },
         "usage_profile": {
          "type": "string",
          "enum": [
           "standard",
           "ev"
          ],
          "default": "standard",
          "description": "ev = heavy overnight use (EV charging); also includes plans for EV owners, which are left out otherwise"
         },
         "payment": {
          "type": "string",
          "enum": [
           "direct_debit",
           "other",
           "payg"
          ],
          "default": "direct_debit"
         },
         "include_cashback": {
          "type": "boolean",
          "default": true
         },
         "supplier": {
          "type": "string",
          "description": "Only this supplier id"
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
         }
        },
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Ranked tariffs",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/QuoteResponse"
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "get": {
    "operationId": "quoteGet",
    "summary": "Rank tariffs (query-string form of POST /v1/energy/quote)",
    "parameters": [
     {
      "name": "market",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "roi",
        "ni"
       ],
       "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)",
       "default": "roi"
      }
     },
     {
      "name": "fuel",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "electricity",
        "gas",
        "dual"
       ],
       "default": "electricity"
      }
     },
     {
      "name": "meter",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "24h",
        "day_night",
        "smart"
       ],
       "default": "24h",
       "description": "The household's meter"
      }
     },
     {
      "name": "region",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "urban",
        "rural"
       ],
       "default": "urban"
      }
     },
     {
      "name": "electricity_kwh",
      "in": "query",
      "schema": {
       "type": "number",
       "exclusiveMinimum": 0,
       "maximum": 200000,
       "description": "Annual kWh; default typical usage (ROI 4,200, NI 3,200)"
      }
     },
     {
      "name": "gas_kwh",
      "in": "query",
      "schema": {
       "type": "number",
       "exclusiveMinimum": 0,
       "maximum": 500000,
       "description": "Annual kWh; default typical usage (ROI 11,000, NI 12,000)"
      }
     },
     {
      "name": "night_share",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1,
       "description": "Share of electricity used 23:00-08:00, for day/night meters (default 0.4) and smart meters (default 0.39)"
      }
     },
     {
      "name": "peak_share",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1,
       "description": "Smart meters: share used 17:00-19:00 (default 0.09)"
      }
     },
     {
      "name": "weekend_share",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 1,
       "description": "Smart meters: share used on Saturday and Sunday (default 2/7)"
      }
     },
     {
      "name": "one_per_supplier",
      "in": "query",
      "schema": {
       "type": "boolean",
       "default": false,
       "description": "Keep only each supplier's cheapest tariff"
      }
     },
     {
      "name": "tag",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "fixed_price",
        "discount",
        "cashback",
        "ev_owners",
        "weekend_rates",
        "free_period",
        "time_of_use",
        "pay_as_you_go"
       ],
       "description": "Rank only tariffs with this tag, e.g. weekend_rates or fixed_price"
      }
     },
     {
      "name": "usage_profile",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "standard",
        "ev"
       ],
       "default": "standard",
       "description": "ev = heavy overnight use (EV charging); also includes plans for EV owners, which are left out otherwise"
      }
     },
     {
      "name": "payment",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "direct_debit",
        "other",
        "payg"
       ],
       "default": "direct_debit"
      }
     },
     {
      "name": "include_cashback",
      "in": "query",
      "schema": {
       "type": "boolean",
       "default": true
      }
     },
     {
      "name": "supplier",
      "in": "query",
      "schema": {
       "type": "string",
       "description": "Only this supplier id"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100,
       "default": 10
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked tariffs",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/QuoteResponse"
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/energy/quote/hdf": {
   "post": {
    "operationId": "quoteFromSmartMeterFile",
    "summary": "Rank ROI tariffs using an ESB Networks smart-meter file (HDF CSV)",
    "requestBody": {
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "file"
        ],
        "properties": {
         "file": {
          "type": "string",
          "format": "binary",
          "description": "HDF CSV downloaded from ESB Networks (max 4 MB)"
         },
         "region": {
          "type": "string",
          "enum": [
           "urban",
           "rural"
          ],
          "default": "urban"
         },
         "payment": {
          "type": "string",
          "enum": [
           "direct_debit",
           "other",
           "payg"
          ],
          "default": "direct_debit"
         },
         "include_cashback": {
          "type": "boolean",
          "default": true
         },
         "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
         },
         "one_per_supplier": {
          "type": "boolean",
          "default": false,
          "description": "Keep only each supplier's cheapest tariff"
         }
        }
       }
      },
      "text/csv": {
       "schema": {
        "type": "string"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Ranked tariffs plus a summary of the file",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/QuoteResponse"
        }
       }
      }
     },
     "413": {
      "description": "File too large"
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/energy/changes": {
   "get": {
    "operationId": "listChanges",
    "summary": "Recent price changes",
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "Default: 30 days ago"
     },
     {
      "name": "market",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "roi",
        "ni"
       ],
       "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 500,
       "default": 100
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Changes",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data_as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When this data was last refreshed (daily)"
          },
          "changes": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Change"
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/solar/estimate": {
   "get": {
    "operationId": "solarEstimate",
    "summary": "Solar PV estimate for a home: generation, savings, SEAI grant, payback",
    "parameters": [
     {
      "name": "county",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Republic of Ireland county, any case (Dublin, cork, Co. Galway)"
      }
     },
     {
      "name": "kwp",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0.5,
       "maximum": 20,
       "description": "System size (default 4 kWp)"
      }
     },
     {
      "name": "panels",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "description": "Panel count (0.44 kWp each) if kwp isn't known"
      }
     },
     {
      "name": "orientation",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "south",
        "southeast",
        "southwest",
        "eastwest"
       ],
       "default": "south"
      }
     },
     {
      "name": "battery_kwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 40,
       "default": 0
      }
     },
     {
      "name": "annual_kwh",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 500,
       "maximum": 50000,
       "description": "Household electricity use (default 4,200)"
      }
     },
     {
      "name": "occupancy",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "away",
        "home"
       ],
       "default": "away",
       "description": "home = someone in during the day"
      }
     },
     {
      "name": "import_rate_c",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "description": "Unit rate in cent/kWh incl. VAT (default 35)"
      }
     },
     {
      "name": "export_rate_c",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "description": "Export payment, cent/kWh (default: median verified supplier rate)"
      }
     },
     {
      "name": "price_eur",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "description": "Quoted price before grant (default: typical price from published packages)"
      }
     },
     {
      "name": "grant_eligible",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean",
       "default": true,
       "description": "SEAI grant: homes built and occupied before 2025"
      }
     },
     {
      "name": "export_tax_pct",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 60,
       "description": "Tax rate (%) on export income above the EUR 400 a year that is tax-free (default 28: standard rate plus USC and PRSI; 0 if under the limit or exempt, about 52 at the higher rate)"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Estimate",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SolarEstimate"
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "post": {
    "operationId": "solarEstimatePost",
    "summary": "Solar PV estimate (JSON body form)",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "county": {
          "type": "string",
          "description": "Republic of Ireland county, any case (Dublin, cork, Co. Galway)"
         },
         "kwp": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 20,
          "description": "System size (default 4 kWp)"
         },
         "panels": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "description": "Panel count (0.44 kWp each) if kwp isn't known"
         },
         "orientation": {
          "type": "string",
          "enum": [
           "south",
           "southeast",
           "southwest",
           "eastwest"
          ],
          "default": "south"
         },
         "battery_kwh": {
          "type": "number",
          "minimum": 0,
          "maximum": 40,
          "default": 0
         },
         "annual_kwh": {
          "type": "number",
          "minimum": 500,
          "maximum": 50000,
          "description": "Household electricity use (default 4,200)"
         },
         "occupancy": {
          "type": "string",
          "enum": [
           "away",
           "home"
          ],
          "default": "away",
          "description": "home = someone in during the day"
         },
         "import_rate_c": {
          "type": "number",
          "description": "Unit rate in cent/kWh incl. VAT (default 35)"
         },
         "export_rate_c": {
          "type": "number",
          "description": "Export payment, cent/kWh (default: median verified supplier rate)"
         },
         "price_eur": {
          "type": "number",
          "description": "Quoted price before grant (default: typical price from published packages)"
         },
         "grant_eligible": {
          "type": "boolean",
          "default": true,
          "description": "SEAI grant: homes built and occupied before 2025"
         },
         "export_tax_pct": {
          "type": "number",
          "minimum": 0,
          "maximum": 60,
          "description": "Tax rate (%) on export income above the EUR 400 a year that is tax-free (default 28: standard rate plus USC and PRSI; 0 if under the limit or exempt, about 52 at the higher rate)"
         }
        },
        "required": [
         "county"
        ],
        "additionalProperties": false
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Estimate",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SolarEstimate"
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/solar/packages": {
   "get": {
    "operationId": "solarPackages",
    "summary": "Published solar packages for a county, ranked by estimated payback (never by commission)",
    "parameters": [
     {
      "name": "county",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "description": "Republic of Ireland county, any case (Dublin, cork, Co. Galway)"
      }
     },
     {
      "name": "battery",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "any",
        "with",
        "without"
       ],
       "default": "any"
      }
     },
     {
      "name": "min_kwp",
      "in": "query",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "max_kwp",
      "in": "query",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "annual_kwh",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 500,
       "maximum": 50000,
       "description": "Household electricity use (default 4,200)"
      }
     },
     {
      "name": "occupancy",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "away",
        "home"
       ],
       "default": "away",
       "description": "home = someone in during the day"
      }
     },
     {
      "name": "orientation",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "south",
        "southeast",
        "southwest",
        "eastwest"
       ],
       "default": "south"
      }
     },
     {
      "name": "import_rate_c",
      "in": "query",
      "schema": {
       "type": "number",
       "description": "Unit rate in cent/kWh incl. VAT (default 35)"
      }
     },
     {
      "name": "export_rate_c",
      "in": "query",
      "schema": {
       "type": "number",
       "description": "Export payment, cent/kWh (default: median verified supplier rate)"
      }
     },
     {
      "name": "export_tax_pct",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0,
       "maximum": 60,
       "description": "Tax rate (%) on export income above the EUR 400 a year that is tax-free (default 28: standard rate plus USC and PRSI; 0 if under the limit or exempt, about 52 at the higher rate)"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 10
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked packages with installer quote_url",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data_as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When the solar data was built"
          },
          "results": {
           "type": "array",
           "items": {
            "type": "object",
            "additionalProperties": true
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/solar/installers": {
   "get": {
    "operationId": "solarInstallers",
    "summary": "SEAI-registered solar PV installers, by county",
    "parameters": [
     {
      "name": "county",
      "in": "query",
      "schema": {
       "type": "string",
       "description": "Republic of Ireland county, any case (Dublin, cork, Co. Galway)"
      }
     },
     {
      "name": "with_prices",
      "in": "query",
      "schema": {
       "type": "boolean",
       "default": false
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 300,
       "default": 50
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Installers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data_as_of": {
           "type": "string",
           "format": "date-time",
           "description": "When the solar data was built"
          },
          "total": {
           "type": "integer"
          },
          "installers": {
           "type": "array",
           "items": {
            "type": "object",
            "additionalProperties": true
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Invalid input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/solar/installers/{seai_reg}": {
   "get": {
    "operationId": "solarInstaller",
    "summary": "One installer with every package it publishes",
    "parameters": [
     {
      "name": "seai_reg",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Installer",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/v1/solar/assumptions": {
   "get": {
    "operationId": "solarAssumptions",
    "summary": "Grants, export rates, model defaults and sources behind the solar estimates",
    "responses": {
     "200": {
      "description": "Assumptions",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "SolarEstimate": {
    "type": "object",
    "properties": {
     "data_as_of": {
      "type": "string",
      "format": "date-time",
      "description": "When the solar data was built"
     },
     "inputs": {
      "type": "object",
      "additionalProperties": true
     },
     "generation_kwh": {
      "type": "integer"
     },
     "self_used_kwh": {
      "type": "integer"
     },
     "exported_kwh": {
      "type": "integer"
     },
     "self_consumption_pct": {
      "type": "number"
     },
     "covers_pct_of_use": {
      "type": "number"
     },
     "annual_saving_eur": {
      "type": "integer",
      "description": "Import saving plus export income, per year"
     },
     "import_saving_eur": {
      "type": "integer"
     },
     "export_income_eur": {
      "type": "integer"
     },
     "price_eur": {
      "type": "integer",
      "description": "Before grant"
     },
     "price_is_typical": {
      "type": "boolean"
     },
     "grant_eur": {
      "type": "integer"
     },
     "net_cost_eur": {
      "type": "integer"
     },
     "payback_years": {
      "type": [
       "number",
       "null"
      ]
     },
     "saving_25y_eur": {
      "type": "integer"
     },
     "disclaimer": {
      "type": "string"
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "detail": {
      "type": "string"
     }
    }
   },
   "Supplier": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "market": {
      "type": "string",
      "enum": [
       "roi",
       "ni"
      ],
      "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)"
     },
     "website": {
      "type": [
       "string",
       "null"
      ]
     },
     "tariffs": {
      "type": "integer"
     },
     "covered": {
      "type": "boolean"
     }
    }
   },
   "Rate": {
    "type": "object",
    "properties": {
     "fuel": {
      "type": "string"
     },
     "kind": {
      "type": "string",
      "enum": [
       "unit",
       "standing",
       "export",
       "levy"
      ]
     },
     "band": {
      "type": "string",
      "description": "all, day, night, peak, ev, boost, nsh, service, pso, carbon_tax, ..."
     },
     "region": {
      "type": "string",
      "enum": [
       "urban",
       "rural",
       "any"
      ]
     },
     "unit": {
      "type": "string",
      "description": "c/kWh, p/kWh, eur/yr, gbp/yr"
     },
     "excl_vat": {
      "type": [
       "number",
       "null"
      ]
     },
     "incl_vat": {
      "type": [
       "number",
       "null"
      ]
     }
    }
   },
   "Tariff": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "supplier": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string"
       },
       "name": {
        "type": "string"
       }
      }
     },
     "name": {
      "type": "string"
     },
     "market": {
      "type": "string",
      "enum": [
       "roi",
       "ni"
      ],
      "description": "roi = Republic of Ireland (EUR), ni = Northern Ireland (GBP)"
     },
     "currency": {
      "type": "string",
      "enum": [
       "EUR",
       "GBP"
      ]
     },
     "fuel": {
      "type": "string",
      "enum": [
       "electricity",
       "gas",
       "dual"
      ]
     },
     "meter_type": {
      "type": "string"
     },
     "payment_method": {
      "type": "string"
     },
     "conditions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "requires_smart_meter": {
      "type": "boolean"
     },
     "pricing": {
      "type": "string",
      "enum": [
       "fixed_rates",
       "dynamic"
      ]
     },
     "valid_from": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "discount_pct": {
      "type": [
       "number",
       "null"
      ]
     },
     "discount_months": {
      "type": [
       "integer",
       "null"
      ]
     },
     "cashback": {
      "type": [
       "number",
       "null"
      ]
     },
     "contract_months": {
      "type": [
       "integer",
       "null"
      ]
     },
     "exit_fee": {
      "type": [
       "number",
       "null"
      ]
     },
     "verification": {
      "type": "object",
      "properties": {
       "level": {
        "type": "string"
       },
       "last_confirmed_at": {
        "type": [
         "string",
         "null"
        ]
       },
       "first_seen": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "source_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "switch_url": {
      "type": "string"
     },
     "rates": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Rate"
      }
     },
     "band_windows": {
      "type": "object",
      "additionalProperties": {
       "type": "array",
       "items": {
        "type": "string"
       }
      }
     }
    }
   },
   "QuoteResult": {
    "type": "object",
    "properties": {
     "rank": {
      "type": "integer"
     },
     "tariff_id": {
      "type": "string"
     },
     "supplier": {
      "type": "string"
     },
     "supplier_id": {
      "type": "string"
     },
     "tariff_name": {
      "type": "string"
     },
     "meter_type": {
      "type": "string"
     },
     "first_year_cost": {
      "type": "number",
      "description": "Incl. VAT, discounts and (if requested) cashback"
     },
     "ongoing_annual_cost": {
      "type": [
       "number",
       "null"
      ],
      "description": "Incl. VAT, once the first-year deal ends (see after_first_year.basis); null when unknown"
     },
     "after_first_year": {
      "type": "object",
      "properties": {
       "cost": {
        "type": [
         "number",
         "null"
        ]
       },
       "basis": {
        "type": "string",
        "enum": [
         "same_rates",
         "same_rates_without_discount",
         "supplier_standard_tariff",
         "fixed_term_ends_rate_unknown"
        ]
       },
       "standard_tariff_id": {
        "type": [
         "string",
         "null"
        ],
        "description": "The standard tariff a fixed deal is assumed to roll onto"
       }
      }
     },
     "discount_pct": {
      "type": [
       "number",
       "null"
      ]
     },
     "discount_months": {
      "type": [
       "integer",
       "null"
      ],
      "description": "How long the discount lasts; 12 (with discount_months_assumed=true) when the price list doesn't say"
     },
     "discount_months_assumed": {
      "type": "boolean"
     },
     "cashback": {
      "type": [
       "number",
       "null"
      ]
     },
     "fixed_price": {
      "type": "boolean",
      "description": "A fixed-price deal (unit rates fixed for the term)"
     },
     "contract_months": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Null when not published in the price list"
     },
     "contract_months_inferred": {
      "type": "boolean",
      "description": "True when contract_months was read from the tariff name"
     },
     "exit_fee": {
      "type": [
       "number",
       "null"
      ]
     },
     "payment_method": {
      "type": "string"
     },
     "conditions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "flags": {
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "new_this_week",
        "over_10pct_cheaper_than_any_other_supplier",
        "cost_after_fixed_term_unknown"
       ]
      }
     },
     "price_list_date": {
      "type": [
       "string",
       "null"
      ],
      "description": "The 'valid from' date printed on the supplier's price list"
     },
     "first_seen": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "When Alva first saw this tariff"
     },
     "last_checked": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "When Alva last confirmed it on the supplier's site"
     },
     "source_url": {
      "type": [
       "string",
       "null"
      ],
      "description": "The supplier's price list or page the rates come from"
     },
     "same_price_as": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Other tariff ids for the same deal at the same price (merged)"
     },
     "breakdown": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      },
      "description": "Excl. VAT components, then VAT"
     },
     "band_kwh": {
      "type": "object",
      "additionalProperties": {
       "type": "number"
      }
     },
     "rates_used": {
      "type": "object",
      "description": "Published unit rates and standing charges (incl. VAT) for the household's region, and the tariff's time bands"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "verification": {
      "type": "string"
     },
     "valid_from": {
      "type": [
       "string",
       "null"
      ],
      "description": "Same as price_list_date (kept for compatibility)"
     },
     "tariff_url": {
      "type": "string"
     },
     "switch_url": {
      "type": "string"
     }
    }
   },
   "QuoteResponse": {
    "type": "object",
    "properties": {
     "data_as_of": {
      "type": "string",
      "format": "date-time",
      "description": "When this data was last refreshed (daily)"
     },
     "assumptions": {
      "type": "object"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/QuoteResult"
      }
     },
     "cheapest_by_supplier": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "supplier": {
         "type": "string"
        },
        "tariff_id": {
         "type": "string"
        },
        "tariff_name": {
         "type": "string"
        },
        "first_year_cost": {
         "type": "number"
        }
       }
      },
      "description": "Each supplier's cheapest result, in rank order"
     },
     "held_for_review": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "supplier": {
         "type": "string"
        },
        "tariff_id": {
         "type": "string"
        },
        "tariff_name": {
         "type": "string"
        },
        "reason": {
         "type": "string"
        }
       }
      },
      "description": "Tariffs left out of the ranking until a rate or price-list date is checked, with the reason"
     },
     "considered": {
      "type": "integer"
     },
     "duplicates_merged": {
      "type": "integer"
     },
     "excluded": {
      "type": "object",
      "additionalProperties": {
       "type": "integer"
      }
     },
     "field_notes": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "disclaimer": {
      "type": "string"
     },
     "accreditation": {
      "type": "string",
      "description": "Independence and commission notice"
     }
    }
   },
   "Change": {
    "type": "object",
    "properties": {
     "detected_at": {
      "type": "string"
     },
     "kind": {
      "type": "string",
      "enum": [
       "new",
       "price_change",
       "expired"
      ]
     },
     "tariff_id": {
      "type": "string"
     },
     "tariff_name": {
      "type": "string"
     },
     "supplier": {
      "type": "string"
     },
     "effective_date": {
      "type": [
       "string",
       "null"
      ]
     },
     "summary": {
      "type": "object"
     }
    }
   }
  }
 }
}