⚡ Octary API

Integrate live UK energy tariff comparisons, Ofgem price cap data, and carbon intensity into your own applications.

Plans & Pricing

Free

£0 /month

100 requests/day
Compare & tariff endpoints
Carbon intensity
Community support

Get Started

Professional

£29 /month

2,000 requests/day
All endpoints
Client management portal
Priority email support
Rate limit headers

Upgrade

Enterprise

£199 /month

50,000 requests/day
All endpoints
Dedicated support
SLA guarantee
White-label option

Authentication

Pass your API key in the X-API-Key request header. Alternatively, use the ?api_key= query parameter.

# Header (recommended)
curl -H "X-API-Key: oky_your_key_here" \
  https://octary.com/api/v1/compare?postcode=SW1A1AA

# Query param (convenient for testing)
curl https://octary.com/api/v1/compare?postcode=SW1A1AA&api_key=oky_your_key_here

Endpoints

GET Compare Tariffs

https://octary.com/api/v1/compare

Returns ranked tariff results for a given postcode, including annual cost estimates and savings vs the Ofgem price cap.

Parameter	Type	Required	Description
`postcode`	string	required	UK postcode e.g. SW1A1AA
`fuel_type`	string	optional	`dual`, `electricity`, or `gas`. Default: `dual`
`elec_kwh`	number	optional	Annual electricity usage in kWh. Default: 2700
`gas_kwh`	number	optional	Annual gas usage in kWh. Default: 11500
`payment_method`	string	optional	`direct_debit` or `prepayment`. Default: `direct_debit`

# Example response
{
  "success": true,
  "postcode": "SW1A1AA",
  "region": "C",
  "ofgem_cap": { "total_annual": 1568.00 },
  "result_count": 12,
  "results": [
    {
      "supplier": "Octopus Energy",
      "tariff_name": "Octopus Flexible",
      "total_annual_cost": 1421.50,
      "saving_vs_cap": 146.50,
      "is_green": true,
      "is_variable": true
    }
  ]
}

GET List Tariffs

https://octary.com/api/v1/tariffs

Returns raw cached tariff data for a DNO region. Useful for building your own comparison logic.

Parameter	Type	Required	Description
`region`	string	required	DNO region code e.g. `C` for London. See /api/v1/regions
`fuel_type`	string	optional	`electricity` or `gas`
`payment_method`	string	optional	Filter by payment method
`green`	integer	optional	Set to `1` to return only green tariffs
`limit`	integer	optional	Max results (1–100). Default: 20

GET Carbon Intensity

https://octary.com/api/v1/carbon

Parameter	Type	Required	Description
`action`	string	optional	`current` (default) or `generation` for generation mix

GET Regions

https://octary.com/api/v1/regions

Returns all 14 UK DNO region codes and names. No parameters required.

GET Ofgem Price Cap

https://octary.com/api/v1/cap

Returns current and recent Ofgem price cap rates (unit rates + standing charges, updated quarterly).

Error Codes

HTTP Code	Meaning
`200`	Success
`400`	Bad request — check your parameters
`401`	Missing or invalid API key
`404`	Unknown endpoint
`422`	Valid request but could not process (e.g. unrecognised postcode)
`429`	Rate limit exceeded — upgrade your plan or wait until midnight UTC

Code Examples

JavaScript (fetch)

const res = await fetch(
  'https://octary.com/api/v1/compare?postcode=SW1A1AA&fuel_type=dual',
  { headers: { 'X-API-Key': 'oky_your_key_here' } }
);
const data = await res.json();
console.log(data.results[0].tariff_name, '— £' + data.results[0].total_annual_cost);

PHP

$ch = curl_init('https://octary.com/api/v1/compare?postcode=SW1A1AA');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: oky_your_key_here'],
]);
$data = json_decode(curl_exec($ch), true);
echo $data['results'][0]['tariff_name'];

Python

import requests

res = requests.get(
    'https://octary.com/api/v1/compare',
    params={'postcode': 'SW1A1AA', 'fuel_type': 'dual'},
    headers={'X-API-Key': 'oky_your_key_here'}
)
data = res.json()
print(data['results'][0]['tariff_name'])