{"openapi":"3.1.0","info":{"title":"SpotVahti API","version":"1.0.0","description":"Independent Finnish electricity contract comparison: yearly cost of spot and fixed-price contracts, supplier terms, spot price statistics and grid transmission fees. Read-only, no authentication.","contact":{"email":"info@spotvahti.fi","url":"https://spotvahti.fi/en/ai/"}},"servers":[{"url":"https://spotvahti.fi"}],"paths":{"/api/compare_electricity_contracts":{"post":{"operationId":"compare_electricity_contracts","summary":"Compare electricity contracts in Finland","description":"Ranks Finnish household electricity contracts (spot/pörssisähkö, fixed-price and hybrid = fixed price ± monthly usage effect) by estimated yearly cost for a given consumption. Spot contracts are priced with realized hourly Nord Pool prices weighted by a typical consumption pattern. Returns the cheapest contracts with margin or energy price, monthly fee, intro offers, price check date and data source. Without postal_code only contracts sold in the whole country are included. Prices exclude grid transmission and electricity tax.","x-openai-isConsequential":false,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"annual_kwh":{"type":"number","minimum":300,"maximum":200000,"description":"Yearly electricity consumption in kWh. If omitted, the home_type default is used."},"home_type":{"type":"string","enum":["apartment","terraced_house","detached_house","ground_source_heat_pump","direct_electric_heating"],"description":"Typical Finnish home type; sets the consumption pattern and default yearly kWh (apartment 2000, terraced_house 5000, detached_house 6000, ground_source_heat_pump 10000, direct_electric_heating 18000)."},"contract_type":{"type":"string","enum":["any","spot","fixed","hybrid"],"default":"any","description":"Filter by contract type."},"postal_code":{"type":"string","pattern":"^\\d{5}$","description":"Finnish postal code. Adds local contracts that are only sold in that area."},"ev_annual_kwh":{"type":"number","minimum":0,"maximum":20000,"description":"Extra yearly kWh for electric car charging at night."},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Number of contracts to return."},"language":{"type":"string","enum":["fi","sv","en"],"description":"Language for texts and links: fi (Finnish), sv (Swedish) or en (English). Use the user's language."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/get_contract":{"post":{"operationId":"get_contract","summary":"Get electricity contract details","description":"Returns the terms (margin or energy price, monthly fee, intro offer, fixed term, restrictions, price check date) and estimated yearly cost of one Finnish electricity contract, found by contract_id or by supplier and product name.","x-openai-isConsequential":false,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contract_id":{"type":"string","description":"contract_id from a previous result."},"supplier":{"type":"string","description":"Supplier name, e.g. \"Helen\" or \"Oomi\"."},"product":{"type":"string","description":"Product name, e.g. \"Pörssisähkö\"."},"annual_kwh":{"type":"number","minimum":300,"maximum":200000},"home_type":{"type":"string","enum":["apartment","terraced_house","detached_house","ground_source_heat_pump","direct_electric_heating"],"description":"Typical Finnish home type; sets the consumption pattern and default yearly kWh (apartment 2000, terraced_house 5000, detached_house 6000, ground_source_heat_pump 10000, direct_electric_heating 18000)."},"language":{"type":"string","enum":["fi","sv","en"],"description":"Language for texts and links: fi (Finnish), sv (Swedish) or en (English). Use the user's language."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/get_supplier":{"post":{"operationId":"get_supplier","summary":"List an electricity supplier's contracts","description":"Lists all contracts of a Finnish electricity supplier in the SpotVahti comparison, with terms and price check dates. An unknown name returns the list of known suppliers.","x-openai-isConsequential":false,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"supplier":{"type":"string","description":"Supplier name, e.g. \"Fortum\"."},"language":{"type":"string","enum":["fi","sv","en"],"description":"Language for texts and links: fi (Finnish), sv (Swedish) or en (English). Use the user's language."}},"required":["supplier"],"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/get_spot_price_statistics":{"post":{"operationId":"get_spot_price_statistics","summary":"Finnish spot price statistics","description":"Realized Finnish day-ahead (Nord Pool) electricity spot price statistics incl. VAT: average over the last 12 months, monthly and yearly averages since 2021, and the average price for each hour of the day with the cheapest and most expensive hours. Not live prices and not a forecast.","x-openai-isConsequential":false,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","enum":["fi","sv","en"],"description":"Language for texts and links: fi (Finnish), sv (Swedish) or en (English). Use the user's language."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/get_network_fees":{"post":{"operationId":"get_network_fees","summary":"Finnish grid transmission fees","description":"Electricity transmission (siirtohinta) price lists of Finnish distribution network companies, incl. VAT: basic fee per month, transmission price per kWh (general, time-of-day or seasonal), power fees, upcoming price lists and the estimated yearly transmission cost incl. electricity tax per home type. Omit network_company to list all covered companies.","x-openai-isConsequential":false,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"network_company":{"type":"string","description":"Network company name, e.g. \"Caruna\", \"Elenia\", \"Helen Sähköverkko\"."},"language":{"type":"string","enum":["fi","sv","en"],"description":"Language for texts and links: fi (Finnish), sv (Swedish) or en (English). Use the user's language."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}