{
"openapi": "3.0.1",
"info": {
"title": "OpenAPI documentation for api.spot-hinta.fi REST interfaces",
"description": "If you want to support development and maintenance of the scripts, go to: https://www.buymeacoffee.com/spothintafiSupported regions: DK1, DK2, EE, FI, LT, LV, NO1, NO2, NO3, NO4, NO5, SE1, SE2, SE3, SE4 - Default region: FINote: Most APIs impose a rate limit of one request per minute per IP address, with a maximum of 1,440 requests permitted within a 24-hour period. Upon exceeding this limit, the API will respond with HTTP status code 429 (Too Many Requests). Failure to reduce the request rate within a reasonable timeframe may result in the temporary suspension of the associated IP address.",
"version": "1.0"
},
"servers": [
{
"url": "https://api.spot-hinta.fi"
}
],
"paths": {
"/DayForward": {
"get": {
"tags": [
"(JSON) Prices tomorrow (if prices already exists)"
],
"operationId": "DayForward",
"parameters": [
{
"name": "region",
"in": "query",
"description": "Region for electricity prices. Default is 'FI'. Supported regions are listed in Swagger information area.",
"schema": {
"type": "string"
}
},
{
"name": "priceResolution",
"in": "query",
"description": "Price resolution in minutes. Allowed values are 15 or 60. Default is 15.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Prices tomorrow as JSON list.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/priceModel"
}
}
}
}
},
"404": {
"description": "Next day prices are not available."
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error. Error report has been sent to the administrators."
}
}
}
},
"/JustNow": {
"get": {
"tags": [
"(JSON) Current hour (or one of the next hours)"
],
"operationId": "JustNow",
"parameters": [
{
"name": "region",
"in": "query",
"description": "Region for electricity prices. Default is 'FI'. Supported regions are listed in Swagger information area.",
"schema": {
"type": "string"
}
},
{
"name": "priceResolution",
"in": "query",
"description": "Price resolution in minutes. Allowed values are 15 or 60. Default is 15.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "lookForwardHours",
"in": "query",
"description": "Use this parameter if you want to look forward to coming hours (1-6). Note! With this parameter, the returned price is a hourly average.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Current hour information as JSON",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/priceModel"
}
}
}
},
"404": {
"description": "Could not load price information."
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error. Error report has been sent to the administrators."
}
}
}
},
"/Html/{fontSize}/{nextHours}": {
"get": {
"tags": [
"(HTML) Current price and next X hours as self-updating HTML page (Javascript required)"
],
"operationId": "JustNowHTML2",
"parameters": [
{
"name": "fontSize",
"in": "path",
"description": "Font size (pt)",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "nextHours",
"in": "path",
"description": "Number of next hours to show (max. 6)",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Current hour as HTML page.",
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Could not load price information."
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error. Error report has been sent to the administrators."
}
}
}
},
"/PostalCodeTemperatures/{postalCode}": {
"get": {
"tags": [
"(JSON) Weather forecast for a postal code in FINLAND or for Latitude/Longitude coordinates."
],
"operationId": "PostalCodeTemperatures",
"parameters": [
{
"name": "postalCode",
"in": "path",
"description": "Postal code (Finnish)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "longitude",
"in": "query",
"description": "Coordinates: longitude, overrides PostalCode. Tip: https://www.latlong.net/",
"schema": {
"type": "string"
}
},
{
"name": "latitude",
"in": "query",
"description": "Coordinates: latitude, overrides PostalCode. Tip: https://www.latlong.net/",
"schema": {
"type": "string"
}
},
{
"name": "HomeAssistant",
"in": "query",
"description": "Returns HOURLY data in a HomeAssistant compatible format.",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Temperature, cloudiness and rain forecast to the selected area as JSON list",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/temperatureDataModel"
}
}
}
}
},
"404": {
"description": "Could not find postal code"
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error while loading postal code information. Error report has been send to the administrator."
}
}
}
},
"/QuickCode/{quickCodeString}": {
"get": {
"tags": [
"(200/400) Response to a given QuickCode."
],
"operationId": "QuickCode",
"parameters": [
{
"name": "quickCode",
"in": "path",
"description": "QuickCode which must be selected from here: https://spot-hinta.fi/Pikakoodit - Finnish region only!",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Hour rank or price is cheap enough.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "Hour rank or price is too expensive.",
"content": {
"text/plain": {
"schema": {
"type": "integer",
"format": "int32"
}
}
}
},
"404": {
"description": "Could not find the given quick code."
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error. Error report has been sent to the administrators."
}
}
}
},
"/Today": {
"get": {
"tags": [
"(JSON) Prices today"
],
"operationId": "Today",
"parameters": [
{
"name": "region",
"in": "query",
"description": "Region for electricity prices. Default is 'FI'. Supported regions are listed in Swagger information area.",
"schema": {
"type": "string"
}
},
{
"name": "priceResolution",
"in": "query",
"description": "Price resolution in minutes. Allowed values are 15 or 60. Default is 15.",
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "Prices today as JSON list.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/priceModel"
}
}
}
}
},
"404": {
"description": "Could not load price information."
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error. Error report has been sent to the administrators."
}
}
}
},
"/TodayAndDayForward": {
"get": {
"tags": [
"(JSON) Price today and tomorrow (if tomorrow prices exist)"
],
"operationId": "TodayAndDayForward",
"parameters": [
{
"name": "region",
"in": "query",
"description": "Region for electricity prices. Default is 'FI'. Supported regions are listed in Swagger information area.",
"schema": {
"type": "string"
}
},
{
"name": "priceResolution",
"in": "query",
"description": "Price resolution in minutes. Allowed values are 15 or 60. Default is 15.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "HomeAssistant",
"in": "query",
"description": "Returns HOURLY data in a HomeAssistant compatible format.",
"schema": {
"type": "boolean"
}
},
{
"name": "HomeAssistant15Min",
"in": "query",
"description": "Returns 15 minutes data in a HomeAssistant compatible format.",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Prices as JSON list.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/priceModel"
}
}
}
}
},
"404": {
"description": "Could not load price information."
},
"429": {
"description": "Too many requests from this IP address. Slow down please."
},
"500": {
"description": "Fatal error. Error report has been sent to the administrators."
}
}
}
}
},
"components": {
"schemas": {
"priceModel": {
"type": "object",
"properties": {
"Rank": {
"type": "integer",
"format": "int32",
"nullable": true
},
"DateTime": {
"type": "string",
"format": "date-time",
"nullable": true
},
"PriceNoTax": {
"type": "number",
"format": "double",
"nullable": true
},
"PriceWithTax": {
"type": "number",
"format": "double",
"nullable": true
}
}
},
"temperatureDataModel": {
"type": "object",
"properties": {
"TimeStamp": {
"type": "string",
"format": "date-time",
"nullable": true
},
"Temperature": {
"type": "number",
"format": "double",
"nullable": true
},
"CloudinessPercentage": {
"type": "number",
"format": "double",
"nullable": true
},
"PrecipitationAmountMm": {
"type": "number",
"format": "double",
"nullable": true
}
}
}
}
}
}