{
  "openapi": "3.1.0",
  "info": {
    "title": "Ellerva — svenska elpriser och elbolag",
    "description": "Gratis öppet API för svensk elprisdata. Realtids spotpriser från Nord Pool (SE1-SE4), månadssnitt, och 130+ svenska elbolag med jämförpriser från Energimarknadsinspektionen. Licensieras under CC BY 4.0 — vid återpublicering krävs synlig länk till ellerva.se.",
    "version": "2.0.0",
    "contact": {
      "name": "Samie Stenberg",
      "email": "samie@ellerva.se",
      "url": "https://ellerva.se"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://ellerva.se",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/spot-prices": {
      "get": {
        "operationId": "getSpotPrices",
        "summary": "Hämta aktuella spotpriser per elområde",
        "description": "Returnerar dagens min-, max- och snittpris i öre/kWh för SE1, SE2, SE3 och SE4. Data från Nord Pool, uppdateras varje timme.",
        "tags": [
          "Prices"
        ],
        "responses": {
          "200": {
            "description": "Aktuella spotpriser per elområde",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpotPricesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/monthly-avg": {
      "get": {
        "operationId": "getMonthlyAverage",
        "summary": "Föregående månads spotprissnitt per elområde",
        "description": "Aritmetiskt medelvärde av dagliga spotpriser för senaste månaden. Matchar branschstandard för prisrankningar (Svekraft, Fortum m.fl. publicerar priser på samma referens).",
        "tags": [
          "Prices"
        ],
        "responses": {
          "200": {
            "description": "Månadssnitt per elområde",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MonthlyAvgResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/providers": {
      "get": {
        "operationId": "getProviders",
        "summary": "Lista elbolag (affiliate-partners eller hela registret)",
        "description": "Svenska elbolag med påslag, månadsavgift, kampanjer och bindningstid. Rankade billigast först.",
        "tags": [
          "Providers"
        ],
        "parameters": [
          {
            "name": "all",
            "in": "query",
            "description": "Sätt till 'true' för hela registret (130+ bolag). Default visar endast affiliate-partners.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista över elbolag",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvidersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/ei-providers": {
      "get": {
        "operationId": "getEiProviders",
        "summary": "Per-leverantör jämförpriser från Energimarknadsinspektionen",
        "description": "130+ elbolag med jämförpris inkl. påslag, månadsavgift, energiskatt och moms. Den faktiska totalkostnaden per kWh.",
        "tags": [
          "Providers"
        ],
        "parameters": [
          {
            "name": "se",
            "in": "query",
            "description": "Elområde (SE1/SE2/SE3/SE4). Obligatorisk.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "SE1",
                "SE2",
                "SE3",
                "SE4"
              ]
            }
          },
          {
            "name": "kwh",
            "in": "query",
            "description": "Årsförbrukning för beräkning. Default 5000.",
            "required": false,
            "schema": {
              "type": "integer",
              "enum": [
                2000,
                5000,
                20000
              ],
              "default": 5000
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Avtalstyp. Default visar alla.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Fast",
                "Rörligt",
                "Timpris",
                "Mix"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Antal resultat (1-500). Default 50.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 50
            }
          },
          {
            "name": "dedupe",
            "in": "query",
            "description": "Sätt till '1' för att gruppera per leverantör (visa billigaste avtalet per bolag).",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista över elbolag och avtal",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EiProvidersResponse"
                }
              }
            }
          },
          "400": {
            "description": "Ogiltigt eller saknat 'se' parameter"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Area": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Elområdets namn"
          },
          "min": {
            "type": "number",
            "description": "Lägsta timpris (öre/kWh)"
          },
          "max": {
            "type": "number",
            "description": "Högsta timpris (öre/kWh)"
          },
          "avg": {
            "type": "number",
            "description": "Snittpris (öre/kWh)"
          }
        }
      },
      "SpotPricesResponse": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "attribution_required": {
            "type": "boolean"
          },
          "unit": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "updated": {
            "type": "string"
          },
          "areas": {
            "type": "object",
            "properties": {
              "SE1": {
                "$ref": "#/components/schemas/Area"
              },
              "SE2": {
                "$ref": "#/components/schemas/Area"
              },
              "SE3": {
                "$ref": "#/components/schemas/Area"
              },
              "SE4": {
                "$ref": "#/components/schemas/Area"
              }
            }
          }
        }
      },
      "MonthlyAvgResponse": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string"
          },
          "month": {
            "type": "string",
            "description": "Format YYYY-MM"
          },
          "attribution": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "attribution_required": {
            "type": "boolean"
          },
          "methodology": {
            "type": "string"
          },
          "areas": {
            "type": "object"
          }
        }
      },
      "ProvidersResponse": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "attribution_required": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "contract_type": {
                  "type": "string"
                },
                "paslag_ore": {
                  "type": "number"
                },
                "manadsavgift_kr": {
                  "type": "number"
                },
                "bindningstid_manader": {
                  "type": "integer",
                  "nullable": true
                },
                "is_affiliate": {
                  "type": "boolean"
                },
                "canonical_url": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "EiProvidersResponse": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "license": {
            "type": "string"
          },
          "attribution_required": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          },
          "filter": {
            "type": "object"
          },
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "avtal_id": {
                  "type": "string"
                },
                "provider_name": {
                  "type": "string"
                },
                "contract_name": {
                  "type": "string",
                  "nullable": true
                },
                "contract_type": {
                  "type": "string"
                },
                "contract_length_months": {
                  "type": "integer",
                  "nullable": true
                },
                "jamforpris_ore": {
                  "type": "number"
                },
                "annual_cost_kr": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Prices",
      "description": "Spotpriser och månadssnitt från Nord Pool"
    },
    {
      "name": "Providers",
      "description": "Svenska elbolag och deras avtal"
    }
  ],
  "externalDocs": {
    "description": "Mänsklig dokumentation med exempel",
    "url": "https://ellerva.se/api/docs"
  }
}