API Documentation

Checking...

Free, real-time UK National Grid data — REST endpoints, a natural-language assistant, and an MCP server for AI clients. No signup required to get started; a free API key raises the MCP rate limit if you need it.

Quick Start

Base URL

https://gridmix.co.uk/api/v1

Try It Now

curl https://gridmix.co.uk/api/v1/current

All endpoints return JSON and support CORS. No authentication needed. Cache responses for 30 seconds to optimize performance.

API Endpoints

GET/api/v1/current

Cache: 30 seconds

Current Grid Data

Get a real-time snapshot of the UK National Grid including demand, generation mix, carbon intensity, frequency, and interconnectors.

Example Response

{
  "timestamp": "2025-11-14T14:40:00Z",
  "demand": {
    "total_mw": 33193,
    "national_mw": 30276,
    "exports_mw": 2917
  },
  "generation": {
    "total_mw": 33193,
    "mix": [
      {
        "fuel": "wind",
        "mw": 16608,
        "percentage": 50
      },
      {
        "fuel": "gas",
        "mw": 8615,
        "percentage": 26
      }
    ]
  },
  "carbon_intensity": {
    "actual": 111,
    "forecast": 111,
    "level": "low"
  },
  "frequency": {
    "hz": 50.099,
    "status": "stable"
  },
  "interconnectors": [
    {
      "name": "IFA",
      "country": "France",
      "flow_mw": 1000,
      "capacity_mw": 2000,
      "direction": "import"
    }
  ],
  "solar": {
    "generation_mw": 4596,
    "capacity_percent": 22.8,
    "installed_capacity_mw": 20200
  },
  "generation_mix_with_solar": {
    "total_mw": 37789,
    "mix": [
      {
        "fuel": "wind",
        "mw": 16608,
        "percentage": 44
      },
      {
        "fuel": "gas",
        "mw": 8615,
        "percentage": 22.8
      },
      {
        "fuel": "solar",
        "mw": 4596,
        "percentage": 12.2
      }
    ],
    "note": "Includes distributed solar from Sheffield Solar PVLive"
  },
  "system_price": {
    "price_gbp_per_mwh": 45.5,
    "timestamp": "2025-11-14T14:30:00Z"
  }
}

GET/api/v1/solar/current

Cache: 30 seconds

Current Solar Generation

Get the current UK solar generation in megawatts and as a percentage of installed capacity.

Example Response

{
  "timestamp": "2026-02-04T12:30:00Z",
  "generation_mw": 4596,
  "capacity_percent": 22.8,
  "installed_capacity_mw": 20200,
  "data_source": "Sheffield Solar PVLive"
}

GET/api/v1/solar/intraday

Cache: 5 minutes

Solar Intraday Curve

Get today's complete solar generation curve with statistics including peak generation, average output, and total energy produced.

Example Response

{
  "date": "2026-02-04",
  "data_points": 48,
  "statistics": {
    "peak_mw": 4596,
    "peak_time": "2026-02-04T12:30:00Z",
    "average_mw": 1920,
    "total_gwh": 46.1
  },
  "data": [
    {
      "timestamp": "2026-02-04T00:00:00Z",
      "time": "00:00",
      "generation_mw": 0
    },
    {
      "timestamp": "2026-02-04T12:30:00Z",
      "time": "12:30",
      "generation_mw": 4596
    }
  ],
  "metadata": {
    "source": "Sheffield Solar PVLive",
    "api_version": "v1",
    "cache_duration": "5 minutes",
    "installed_capacity_mw": 20200
  }
}

GET/api/v1/historical

Cache: 5 minutes

Historical Data

Get historical carbon intensity and demand data for analysis and trend tracking.

Query Parameters

hoursintegerdefault: 24Number of hours to retrieve (1-168)

limitintegerdefault: 100Maximum number of data points (1-1000)

Example Response

{
  "hours_requested": 24,
  "data_points": 48,
  "data": [
    {
      "timestamp": "2025-11-14T00:00:00Z",
      "demand_mw": 28456,
      "carbon_intensity": {
        "actual": 77,
        "forecast": 77,
        "level": "low"
      }
    }
  ]
}

GET/api/v1/forecast

Cache: 5 minutes

Carbon Intensity Forecast

Get carbon intensity forecasts to plan energy usage during cleaner periods.

Query Parameters

hoursintegerdefault: 48Hours ahead to forecast (1-168)

limitintegerdefault: 100Maximum number of data points (1-1000)

Example Response

{
  "generated_at": "2025-11-14T14:45:19.029Z",
  "forecast_hours": 48,
  "data_points": 96,
  "data": [
    {
      "timestamp": "2025-11-14T15:00:00Z",
      "carbon_intensity": {
        "forecast": 113,
        "level": "low"
      }
    }
  ]
}

MCP Server for AI Assistants

Connect Claude, Claude Desktop, or any MCP-compatible client directly to GridMix. The server exposes the same tools Watt uses internally as native tool calls, so an assistant can query live and historical UK grid data instead of guessing.

Endpoint

https://gridmix.co.uk/api/mcp

Streamable HTTP transport, stateless. Standard MCP methods: initialize, tools/list, tools/call.

How to Connect

In Claude.ai or Claude Desktop, go to Settings → Connectors
Choose Add custom connector
Paste the endpoint URL above and save
Ask a question — Claude will call GridMix's tools directly

Available Tools

get_current_mix

Live UK generation mix (wind, gas, nuclear, etc.), carbon intensity, and interconnector flows.

get_stats

Current renewable %, fossil %, nuclear %, low-carbon %, and demand.

get_intensity_history

Carbon intensity for each settlement period over the last N hours (1-168).

get_intensity_forecast

Carbon intensity outlook for the next N hours (1-168).

get_solar

Solar generation: current snapshot, today's curve, or yesterday's curve.

get_frequency

Current grid frequency in Hz and stability status.

get_price

Current GB wholesale system price in GBP/MWh.

get_health_score

GridMix's composite Grid Health Score (0-100, with letter grade).

get_historical_year

Annual summary (renewables, price, demand, carbon) for a year, 2000-2025.

get_historical_month

Monthly snapshot for a given year and month, 2000-2025.

get_historical_record

Highest or lowest value of a metric across the full historical archive.

Rate limit: 20 requests/day per IP with no key, or 500/day with a free API key. (The REST GET endpoints above are unlimited; Watt's natural-language endpoint is capped at 30/day per IP.)

Get a Free API Key

No account, no verification — just an email address. Raises your MCP rate limit from 20 to 500 requests/day.

Code Examples

// Fetch current grid data
const response = await fetch('https://gridmix.co.uk/api/v1/current');
const data = await response.json();

console.log('Demand:', data.demand.total_mw, 'MW');
console.log('Carbon:', data.carbon_intensity.actual, 'gCO2/kWh');
console.log('Renewable %:',
  data.generation.mix
    .filter(f => ['wind', 'solar', 'hydro'].includes(f.fuel))
    .reduce((sum, f) => sum + f.percentage, 0)
);

// Get historical data with error handling
try {
  const historical = await fetch(
    'https://gridmix.co.uk/api/v1/historical?hours=24'
  );
  const histData = await historical.json();

  // Find cleanest period
  const cleanest = histData.data.reduce((min, point) =>
    point.carbon_intensity.actual < min.carbon_intensity.actual ? point : min
  );

  console.log('Cleanest period:', cleanest.timestamp);
  console.log('Carbon intensity:', cleanest.carbon_intensity.actual);
} catch (error) {
  console.error('API Error:', error);
}

Error Codes & Handling

200OK

Request successful

400Bad Request

Invalid parameters (e.g., hours out of range)

404Not Found

Endpoint or resource not found

429Too Many Requests

Rate limit exceeded on /api/v1/watt (30/day per IP) or /api/mcp (20/day per IP, 500/day with a free API key)

500Internal Server Error

Something went wrong on our end

Example Error Response

{
  "error": "Failed to fetch grid data",
  "message": "Upstream API timeout",
  "timestamp": "2026-06-29T09:38:14.664Z"
}

Real-World Use Cases

EV Charging Optimization

Charge your electric vehicle during low carbon periods

if (carbon < 100) startCharging()

Smart Home Automation

Run appliances when the grid is greenest

if (renewable > 70%) runDishwasher()

Energy Analytics

Analyze trends and forecast renewable energy availability

analyzeRenewableTrends(data)

Cost Optimization

Reduce energy costs with dynamic pricing

if (carbon < threshold) useEnergy()

Carbon Tracking

Monitor and reduce your carbon footprint

trackCarbonEmissions(data)

Grid Monitoring

Real-time monitoring of UK electricity grid

displayGridStatus(current)

Fair Use Policy

GridMix API is 100% free for everyone. The REST GET endpoints are unlimited with no signup at all; Watt and the MCP server carry daily per-IP caps to keep things fast for everyone. The MCP server's cap can be raised with a free API key (just an email, no verification). We trust our community to use it responsibly.

Best Practices

Cache responses for at least 30 seconds
Use appropriate query parameters
Handle errors gracefully
Free for personal and commercial use
No signup needed for REST endpoints; free API key for higher MCP limits

Please Avoid

Exceeding 30 requests/day on Watt or your MCP server limit (20/day, 500/day with a key)
Scraping or bulk downloading
Using as primary data source without caching
Redistributing data commercially

Need higher throughput? Contact us at hello@gridmix.co.uk and we'll work with you to find a solution.

Support GridMix

GridMix is free and open source. If you find it valuable, consider supporting the project to help keep it running for everyone.

Star on GitHub Support the Project