{ "openapi": "3.1.0", "info": { "title": "UtilityPrices open data API", "version": "1.0.0", "summary": "Free, read-only UK energy price and grid data.", "description": "No key needed. GET only; CORS is open to every origin. Every response carries its period, units, VAT basis, sources, retrieval date, attribution and licence. Please credit UtilityPrices with a link. Full guide: https://utilityprices.co.uk/developers", "license": { "name": "Creative Commons Attribution 4.0 International", "identifier": "CC-BY-4.0" }, "contact": { "name": "UtilityPrices", "url": "https://utilityprices.co.uk/about" } }, "externalDocs": { "description": "Guide, CSV downloads and embeddable widgets", "url": "https://utilityprices.co.uk/developers" }, "servers": [ { "url": "https://utilityprices.co.uk" } ], "tags": [ { "name": "Prices", "description": "Dated benchmarks from official sources" }, { "name": "Live data", "description": "Near-real-time grid readings" }, { "name": "Meta" } ], "paths": { "/api/v1": { "get": { "operationId": "index", "summary": "List endpoints, downloads and widgets", "tags": [ "Meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "openapi", "summary": "This OpenAPI 3.1 document", "tags": [ "Meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/price-cap": { "get": { "operationId": "priceCap", "summary": "Energy price cap summary", "description": "Ofgem headline typical bill, GB average Direct Debit unit rates and standing charges, typical bills by payment method, typical consumption values and the announcement timetable. Updates: Quarterly, when Ofgem announces a new cap.", "tags": [ "Prices" ], "externalDocs": { "url": "https://utilityprices.co.uk/developers/api#price-cap" }, "parameters": [], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "geography": { "type": "string" }, "announcedAt": { "type": "string", "format": "date" }, "headline": { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "typicalAnnualBillGbp": { "type": "number" }, "previousTypicalAnnualBillGbp": { "type": "number" }, "previousPeriod": { "type": "string" }, "changeGbp": { "type": "number" }, "changePercent": { "type": "number" } }, "required": [ "paymentMethod", "typicalAnnualBillGbp", "previousTypicalAnnualBillGbp", "previousPeriod", "changeGbp", "changePercent" ] }, "gbAverage": { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "electricityMeter": { "type": "string" }, "electricity": { "$ref": "#/components/schemas/FuelRates" }, "gas": { "$ref": "#/components/schemas/FuelRates" }, "typicalAnnualCostGbp": { "$ref": "#/components/schemas/AnnualCosts" }, "typicalAnnualCostBasis": { "type": "string" } }, "required": [ "paymentMethod", "electricityMeter", "electricity", "gas", "typicalAnnualCostGbp", "typicalAnnualCostBasis" ] }, "byPaymentMethod": { "type": "array", "items": { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "previousTypicalAnnualBillGbp": { "type": "number" }, "typicalAnnualBillGbp": { "type": "number" }, "changePercent": { "type": "number" } }, "required": [ "paymentMethod", "previousTypicalAnnualBillGbp", "typicalAnnualBillGbp", "changePercent" ] } }, "typicalConsumptionKwh": { "type": "object" }, "nextAnnouncements": { "type": "array", "items": { "type": "object", "properties": { "announceBy": { "type": "string", "format": "date" }, "periodFrom": { "type": "string", "format": "date" }, "periodTo": { "type": "string", "format": "date" } }, "required": [ "announceBy", "periodFrom", "periodTo" ] } } }, "required": [ "geography", "announcedAt", "headline", "gbAverage", "byPaymentMethod", "typicalConsumptionKwh", "nextAnnouncements" ] } }, "required": [ "data" ] } ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/price-cap/regions": { "get": { "operationId": "priceCapRegions", "summary": "Price cap rates for all 14 regions", "description": "Direct Debit, single-rate electricity and gas unit rates and standing charges for each GB price-cap region, with typical annual costs and ranks. Updates: Quarterly, when Ofgem announces a new cap.", "tags": [ "Prices" ], "externalDocs": { "url": "https://utilityprices.co.uk/developers/api#price-cap-regions" }, "parameters": [], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "electricityMeter": { "type": "string" }, "typicalConsumptionKwh": { "type": "object", "properties": { "electricity": { "type": "number" }, "gas": { "type": "number" } }, "required": [ "electricity", "gas" ] }, "derivation": { "type": "string" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } }, "required": [ "paymentMethod", "electricityMeter", "typicalConsumptionKwh", "derivation", "regions" ] } }, "required": [ "data" ] } ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/price-cap/regions/{region}": { "get": { "operationId": "priceCapRegion", "summary": "Price cap rates for one region", "description": "The same figures for a single region, selected by its slug. Updates: Quarterly, when Ofgem announces a new cap.", "tags": [ "Prices" ], "externalDocs": { "url": "https://utilityprices.co.uk/developers/api#price-cap-region" }, "parameters": [ { "name": "region", "in": "path", "required": true, "description": "Region slug, for example london or north-western-england. GET /api/v1/price-cap/regions lists every slug.", "schema": { "type": "string", "enum": [ "east-midlands", "eastern-england", "london", "merseyside-and-northern-wales", "north-eastern-england", "north-western-england", "northern-scotland", "south-eastern-england", "south-western-england", "southern-england", "southern-scotland", "southern-wales", "west-midlands", "yorkshire" ] } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Region" }, { "type": "object", "properties": { "paymentMethod": { "type": "string" }, "electricityMeter": { "type": "string" }, "typicalConsumptionKwh": { "type": "object", "properties": { "electricity": { "type": "number" }, "gas": { "type": "number" } }, "required": [ "electricity", "gas" ] }, "gbAverage": { "type": "object", "properties": { "electricity": { "$ref": "#/components/schemas/FuelRates" }, "gas": { "$ref": "#/components/schemas/FuelRates" }, "typicalAnnualCostGbp": { "$ref": "#/components/schemas/AnnualCosts" } }, "required": [ "electricity", "gas", "typicalAnnualCostGbp" ] } }, "required": [ "paymentMethod", "electricityMeter", "typicalConsumptionKwh", "gbAverage" ] } ] } }, "required": [ "data" ] } ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/vat-relief": { "get": { "operationId": "vatRelief", "summary": "Electricity VAT relief", "description": "The temporary 0% VAT rate on household electricity in Great Britain: dates, rates, scope and official sources. Updates: When HMRC or GOV.UK guidance changes.", "tags": [ "Prices" ], "externalDocs": { "url": "https://utilityprices.co.uk/developers/api#vat-relief" }, "parameters": [], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "geography": { "type": "string" }, "previousRatePercent": { "type": "number" }, "temporaryRatePercent": { "type": "number" }, "announcedAverageSavingGbpPerYear": { "type": "number" }, "announcedAt": { "type": "string", "format": "date" }, "electricityDeMinimis": { "type": "string" }, "appliesTo": { "type": "array", "items": { "type": "string" } }, "doesNotApplyTo": { "type": "array", "items": { "type": "string" } } }, "required": [ "geography", "previousRatePercent", "temporaryRatePercent", "announcedAverageSavingGbpPerYear", "announcedAt", "electricityDeMinimis", "appliesTo", "doesNotApplyTo" ] } }, "required": [ "data" ] } ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/business-prices": { "get": { "operationId": "businessPrices", "summary": "Business energy prices by band", "description": "DESNZ average prices paid by UK non-domestic consumers for electricity and gas, by annual consumption band, including and excluding Climate Change Levy. Updates: Quarterly, with each DESNZ release.", "tags": [ "Prices" ], "externalDocs": { "url": "https://utilityprices.co.uk/developers/api#business-prices" }, "parameters": [ { "name": "fuel", "in": "query", "required": false, "description": "Return only one fuel.", "schema": { "type": "string", "enum": [ "electricity", "gas" ] } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400, stale-while-revalidate=86400" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "geography": { "type": "string" }, "measure": { "type": "string" }, "electricity": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBand" } }, "gas": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessBand" } } }, "required": [ "geography", "measure" ] } }, "required": [ "data" ] } ] } } } }, "400": { "description": "Invalid fuel parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/grid/electricity": { "get": { "operationId": "gridElectricity", "summary": "Live GB electricity generation mix", "description": "The latest half-hourly Great Britain generation mix by fuel, renewable share and carbon intensity from the NESO Carbon Intensity API. Updates: Every half hour; cached for two minutes.", "tags": [ "Live data" ], "externalDocs": { "url": "https://utilityprices.co.uk/developers/api#grid-electricity" }, "parameters": [], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=60, s-maxage=120, stale-while-revalidate=60" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "current", "stale" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "renewablePercentage": { "type": "number" }, "mix": { "type": "array", "items": { "type": "object", "properties": { "fuel": { "type": "string" }, "label": { "type": "string" }, "percentage": { "type": "number" } }, "required": [ "fuel", "label", "percentage" ] } }, "carbonIntensity": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "value": { "type": "number" }, "kind": { "type": "string", "enum": [ "actual", "forecast" ] }, "to": { "type": "string", "format": "date-time" } }, "required": [ "value", "kind", "to" ] } ] } }, "required": [ "status", "from", "to", "renewablePercentage", "mix", "carbonIntensity" ] } }, "required": [ "data" ] } ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream feed unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "FuelRates": { "type": "object", "properties": { "unitRatePencePerKwh": { "type": "number" }, "standingChargePencePerDay": { "type": "number" }, "vatPercent": { "type": "number" }, "vatIncluded": { "type": "boolean" } }, "required": [ "unitRatePencePerKwh", "standingChargePencePerDay", "vatPercent", "vatIncluded" ] }, "AnnualCosts": { "type": "object", "properties": { "electricity": { "type": "number" }, "gas": { "type": "number" }, "dualFuel": { "type": "number" } }, "required": [ "electricity", "gas", "dualFuel" ] }, "Region": { "type": "object", "properties": { "region": { "type": "string" }, "slug": { "type": "string" }, "electricity": { "$ref": "#/components/schemas/FuelRates" }, "gas": { "$ref": "#/components/schemas/FuelRates" }, "typicalAnnualCostGbp": { "$ref": "#/components/schemas/AnnualCosts" }, "rankLowestFirst": { "type": "object", "properties": { "dualFuel": { "type": "integer" }, "electricityUnit": { "type": "integer" }, "electricityStanding": { "type": "integer" }, "gasUnit": { "type": "integer" }, "gasStanding": { "type": "integer" } }, "required": [ "dualFuel", "electricityUnit", "electricityStanding", "gasUnit", "gasStanding" ] } }, "required": [ "region", "slug", "electricity", "gas", "typicalAnnualCostGbp", "rankLowestFirst" ] }, "BusinessBand": { "type": "object", "properties": { "band": { "type": "string" }, "annualConsumptionMwh": { "type": "string" }, "excludingCclPencePerKwh": { "type": "number" }, "includingCclPencePerKwh": { "type": "number" } }, "required": [ "band", "annualConsumptionMwh", "excludingCclPencePerKwh", "includingCclPencePerKwh" ] }, "Envelope": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "dataset": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "period": { "type": "object", "description": "effectiveFrom/effectiveTo (YYYY-MM-DD) for dated benchmarks; from/to (ISO 8601) for live readings" }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "vatBasis": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "source": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "publisher": { "type": "string" } }, "required": [ "title", "url", "publisher" ] } }, "retrievedAt": { "type": "string" }, "updates": { "type": "string" }, "attribution": { "type": "object", "properties": { "required": { "type": "boolean" }, "text": { "type": "string" }, "html": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "note": { "type": "string" } }, "required": [ "required", "text", "html", "url", "note" ] }, "licence": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "upstream": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "publisher": { "type": "string" }, "licence": { "type": "string" }, "url": { "type": "string" } }, "required": [ "source", "publisher", "licence", "url" ] } } }, "required": [ "id", "name", "url", "upstream" ] }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "page": { "type": "string" }, "docs": { "type": "string" }, "csv": { "type": "string" } }, "required": [ "self", "page", "docs" ] } }, "required": [ "apiVersion", "dataset", "title", "description", "period", "units", "vatBasis", "notes", "source", "retrievedAt", "updates", "attribution", "licence", "links" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "not_found", "region_not_found", "invalid_parameter", "method_not_allowed", "upstream_unavailable" ] }, "message": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "status", "code", "message", "docs" ] } }, "required": [ "error" ] } } } }