{ "openapi": "3.0.3", "info": { "title": "Elecz Electricity Price Signal API", "version": "1.9.2", "description": "Real-time electricity spot prices, cheapest hours, and contract comparison for 31 countries across Europe and Oceania. No authentication required.", "contact": { "name": "Zemlo AI / Elecz", "url": "https://elecz.com" } }, "servers": [ { "url": "https://elecz.com", "description": "Production server" } ], "paths": { "/signal/spot": { "get": { "summary": "Current electricity spot price", "description": "Returns the real-time electricity spot price for the selected zone. Use when the user asks what electricity costs right now. Prices are in local currency units: NZD c/kWh for NZ, AUD c/kWh for AU, p/kWh for GB, c/kWh for EUR zones, ore/kWh for SEK/NOK/DKK zones. Updated hourly for Nordic/DE, every 30 minutes for GB/AU/NZ.", "operationId": "getSpotPrice", "parameters": [ { "name": "zone", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "FI", "SE", "SE1", "SE2", "SE3", "SE4", "NO", "NO1", "NO2", "NO3", "NO4", "NO5", "DK", "DK1", "DK2", "DE", "NL", "BE", "AT", "FR", "IT", "PL", "CZ", "HU", "RO", "ES", "PT", "HR", "BG", "SI", "SK", "GR", "EE", "LV", "LT", "CH", "RS", "BA", "ME", "MK", "GB", "AU-NSW", "AU-VIC", "AU-QLD", "AU-SA", "AU-TAS", "NZ-NI", "NZ-SI" ] }, "description": "Market zone. ENTSO-E: FI, SE, SE1-SE4, NO, NO1-NO5, DK, DK1-DK2, DE, NL, BE, AT, FR, IT, PL, CZ, HU, RO, ES, PT, HR, BG, SI, SK, GR, EE, LV, LT, CH, RS, BA, ME, MK. UK: GB. Australia: AU-NSW, AU-VIC, AU-QLD, AU-SA, AU-TAS. New Zealand: NZ-NI, NZ-SI." } ], "responses": { "200": { "description": "Current spot price", "content": { "application/json": { "schema": { "type": "object", "properties": { "signal": { "type": "string", "example": "elecz_spot" }, "zone": { "type": "string", "example": "FI" }, "currency": { "type": "string", "example": "EUR" }, "price": { "type": "number", "example": 6.745 }, "unit": { "type": "string", "example": "c/kWh" }, "timestamp": { "type": "string", "format": "date-time" }, "powered_by": { "type": "string", "example": "Elecz.com" } } }, "example": { "signal": "elecz_spot", "zone": "FI", "currency": "EUR", "price": 6.745, "unit": "c/kWh", "timestamp": "2026-04-13T05:47:50Z", "powered_by": "Elecz.com" } } } } } } }, "/signal/cheapest-hours": { "get": { "summary": "Cheapest electricity hours in next 24h", "description": "Returns the cheapest hours in the next 24 hours with current-hour context signals. Use when the user asks when to run appliances, charge an EV, or schedule high-consumption tasks. AU and NZ zones return available: false — no public day-ahead data exists for those markets.", "operationId": "getCheapestHours", "parameters": [ { "name": "zone", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "FI", "SE", "SE1", "SE2", "SE3", "SE4", "NO", "NO1", "NO2", "NO3", "NO4", "NO5", "DK", "DK1", "DK2", "DE", "NL", "BE", "AT", "FR", "IT", "PL", "CZ", "HU", "RO", "ES", "PT", "HR", "BG", "SI", "SK", "GR", "EE", "LV", "LT", "CH", "RS", "BA", "ME", "MK", "GB", "AU-NSW", "AU-VIC", "AU-QLD", "AU-SA", "AU-TAS", "NZ-NI", "NZ-SI" ] }, "description": "Market zone. AU and NZ zones return available: false." }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 5 }, "description": "Number of cheapest slots to return." }, { "name": "window", "in": "query", "required": false, "schema": { "type": "integer", "default": 24 }, "description": "Hours to look ahead." } ], "responses": { "200": { "description": "Cheapest hours response", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "zone": { "type": "string" }, "currency": { "type": "string" }, "unit": { "type": "string" }, "energy_state": { "type": "string", "enum": ["cheap", "normal", "expensive", "negative", "unknown"], "description": "Spot price vs daily average. cheap = below 70% of avg. Independent from current_hour_is_cheap." }, "confidence": { "type": "number" }, "current_hour_signal": { "type": "string", "enum": ["low", "medium", "high"], "description": "Relative position in today's price distribution. low = rank 1-8, medium = 9-16, high = 17-24. Returns medium if day prices are flat (spread < 20% of average)." }, "current_hour_is_cheap": { "type": "boolean", "description": "true if the current hour is in the cheapest_hours list. Independent from energy_state." }, "current_hour_rank": { "type": "integer", "nullable": true, "description": "Rank 1-n in today's price distribution (1 = cheapest). Dense rank — ties share the lowest rank. null if no data." }, "cheap_window_ends": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 UTC — when the current consecutive cheap block ends. null if not currently in a cheap hour." }, "next_cheap_hour": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO 8601 UTC — start of the next cheap hour. null if currently in a cheap hour or no future cheap hours in window." }, "hours_until_next_cheap": { "type": "integer", "nullable": true, "description": "Hours until next cheap hour. 0 = current hour is cheap, start now. null = no future cheap hours in window (data gap)." }, "cheap_hours_remaining_today": { "type": "integer", "description": "Cheap hours still ahead in the window (UTC-based). Includes next-day hours if includes_next_day is true." }, "includes_next_day": { "type": "boolean", "description": "true if the window contains price data beyond today UTC." }, "data_complete": { "type": "boolean", "description": "true if ~24h of price data is available. false = treat signals with caution." }, "cheapest_hours": { "type": "array", "description": "Cheapest slots sorted chronologically.", "items": { "type": "object", "properties": { "hour": { "type": "string", "description": "YYYY-MM-DDTHH:MM (UTC, no timezone suffix)" }, "price": { "type": "number" }, "unit": { "type": "string" } } } }, "best_3h_window": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "avg_price": { "type": "number" }, "note": { "type": "string" } } }, "avoid_hours": { "type": "array", "items": { "type": "string" } }, "recommendation": { "type": "string", "enum": ["run_high_consumption_tasks", "normal_usage", "avoid_high_consumption"] }, "powered_by": { "type": "string" } } }, "example": { "available": true, "zone": "FI", "currency": "EUR", "unit": "c/kWh", "energy_state": "cheap", "confidence": 0.9, "current_hour_signal": "low", "current_hour_is_cheap": false, "current_hour_rank": 5, "cheap_window_ends": null, "next_cheap_hour": "2026-04-20T10:00:00+00:00", "hours_until_next_cheap": 1, "cheap_hours_remaining_today": 5, "includes_next_day": true, "data_complete": true, "cheapest_hours": [ { "hour": "2026-04-20T10:00", "price": 5.476, "unit": "c/kWh" }, { "hour": "2026-04-20T11:00", "price": 5.769, "unit": "c/kWh" }, { "hour": "2026-04-20T12:00", "price": 5.896, "unit": "c/kWh" }, { "hour": "2026-04-20T14:00", "price": 5.410, "unit": "c/kWh" }, { "hour": "2026-04-20T15:00", "price": 5.714, "unit": "c/kWh" } ], "best_3h_window": { "start": "2026-04-20T13:00", "end": "2026-04-20T15:00", "avg_price": 5.6917, "note": "end is the start of the last cheap slot in the window" }, "avoid_hours": ["2026-04-21T02:00", "2026-04-20T21:00"], "recommendation": "run_high_consumption_tasks", "powered_by": "Elecz.com" } } } } } } }, "/signal": { "get": { "summary": "Full energy signal with contract comparison", "description": "Returns spot price, energy state, and ranked contract comparison in one call. Use when the user asks which electricity contract to choose, whether to switch provider, or wants a full overview of their energy situation.", "operationId": "getFullSignal", "parameters": [ { "name": "zone", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "FI", "SE", "SE1", "SE2", "SE3", "SE4", "NO", "NO1", "NO2", "NO3", "NO4", "NO5", "DK", "DK1", "DK2", "DE", "NL", "BE", "AT", "FR", "IT", "PL", "CZ", "HU", "RO", "ES", "PT", "HR", "BG", "SI", "SK", "GR", "EE", "LV", "LT", "CH", "RS", "BA", "ME", "MK", "GB", "AU-NSW", "AU-VIC", "AU-QLD", "AU-SA", "AU-TAS", "NZ-NI", "NZ-SI" ] } }, { "name": "consumption", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Annual kWh consumption. Defaults: NZ 8000, AU 4500, GB 2700, DE 3500, Nordic 2000." }, { "name": "heating", "in": "query", "required": false, "schema": { "type": "string", "enum": ["district", "electric"], "default": "district" } } ], "responses": { "200": { "description": "Full signal response", "content": { "application/json": { "schema": { "type": "object", "properties": { "signal": { "type": "string" }, "version": { "type": "string" }, "zone": { "type": "string" }, "currency": { "type": "string" }, "unit": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "energy_state": { "type": "string", "enum": ["cheap", "normal", "expensive", "negative", "unknown"] }, "is_good_time_to_use_energy": { "type": "boolean" }, "switch_recommended": { "type": "boolean" }, "confidence": { "type": "number" }, "spot_price": { "type": "object", "properties": { "value": { "type": "number" }, "local": { "type": "number" }, "unit": { "type": "string" } } }, "best_contract": { "type": "object", "properties": { "provider": { "type": "string" }, "type": { "type": "string" }, "spot_margin_ckwh": { "type": "number", "nullable": true }, "arbeitspreis_ckwh": { "type": "number", "nullable": true }, "basic_fee_eur_month": { "type": "number", "nullable": true }, "annual_cost_estimate": { "type": "number" }, "trust_score": { "type": "integer" } } }, "top_contracts": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "provider": { "type": "string" }, "type": { "type": "string" }, "spot_margin_ckwh": { "type": "number", "nullable": true }, "arbeitspreis_ckwh": { "type": "number", "nullable": true }, "basic_fee_eur_month": { "type": "number", "nullable": true }, "annual_cost_estimate": { "type": "number" }, "trust_score": { "type": "integer" }, "provider_url": { "type": "string" } } } }, "decision_hint": { "type": "string" }, "reason": { "type": "string" }, "action": { "type": "object", "properties": { "type": { "type": "string" }, "available": { "type": "boolean" }, "action_link": { "type": "string" }, "expected_savings_year": { "type": "number", "nullable": true }, "expected_savings_local_year": { "type": "number", "nullable": true }, "savings_currency": { "type": "string" }, "savings_basis": { "type": "string" }, "confidence": { "type": "number" }, "status": { "type": "string" } } }, "powered_by": { "type": "string" } } }, "example": { "signal": "elecz", "version": "1.9.2", "zone": "FI", "currency": "EUR", "unit": "c/kWh", "energy_state": "normal", "is_good_time_to_use_energy": false, "switch_recommended": false, "confidence": 0.95, "spot_price": { "value": 6.745, "local": 6.745, "unit": "c/kWh" }, "best_contract": { "provider": "vare", "type": "spot", "spot_margin_ckwh": 0.36, "basic_fee_eur_month": 3.5, "annual_cost_estimate": 184.1, "trust_score": 60 }, "top_contracts": [ { "rank": 1, "provider": "vare", "type": "spot", "spot_margin_ckwh": 0.36, "basic_fee_eur_month": 3.5, "annual_cost_estimate": 184.1, "trust_score": 60, "provider_url": "https://www.vare.fi/sahkosopimus" }, { "rank": 2, "provider": "vattenfall", "type": "spot", "spot_margin_ckwh": 0.27, "basic_fee_eur_month": 3.99, "annual_cost_estimate": 188.18, "trust_score": 100, "provider_url": "https://www.vattenfall.fi/sahko/sahkosopimus" } ], "decision_hint": "spot_recommended", "reason": "Low consumption: minimize basic fee. Spot is cheapest long-term.", "action": { "type": "monitor", "available": true, "action_link": "https://elecz.com/go/vare", "expected_savings_year": 8.08, "savings_currency": "EUR", "savings_basis": "vs_median_provider", "confidence": 0.95, "status": "monitor" }, "powered_by": "Elecz.com" } } } } } } }, "/go/{provider}": { "get": { "summary": "Redirect to provider website", "description": "Redirects to the electricity provider's website with click analytics tracking.", "operationId": "goToProvider", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Provider identifier, e.g. tibber, vattenfall, octopus_agile." }, { "name": "zone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Market zone for correct provider URL routing." } ], "responses": { "302": { "description": "Redirect to provider URL" }, "404": { "description": "Provider not found" } } } }, "/health": { "get": { "summary": "Health check", "description": "Returns API health status and version.", "operationId": "getHealth", "responses": { "200": { "description": "Health OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "elecz" }, "version": { "type": "string", "example": "1.9.2" } } } } } } } } } } }