# GridPulse — Electricity Price API

The electricity price API for developers and AI agents. Real-time and historical wholesale electricity prices, carbon intensity, generation mix, gas storage, weather, and analytics for **41+ bidding zones** across Europe, Great Britain, the United States, and Australia — plus monthly carbon intensity for **70+ countries worldwide**.

[![API Status](https://img.shields.io/badge/API-Live-brightgreen)](https://stats.uptimerobot.com/J5zSXoBKy5)
[![npm](https://img.shields.io/npm/v/gridpulse-mcp)](https://www.npmjs.com/package/gridpulse-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 🔑 Get an API Key

**Basic tier is free — no API key needed** for 500 requests/month.

👉 **[Get your API key on RapidAPI](https://rapidapi.com/devtee000/api/gridpulse-energy)**

| Plan | Price | Requests/month | Rate Limit |
|------|-------|----------------|------------|
| Basic | Free | 500 | 1 req/sec |
| Pro | $29/mo | 10,000 | 10 req/sec |
| Ultra | $99/mo | 60,000 | 25 req/sec |
| Mega | $299/mo | 250,000 | 50 req/sec |

---

## 🌐 Links

- **Website**: [gridpulse.network](https://gridpulse.network)
- **API**: [api.gridpulse.network](https://api.gridpulse.network)
- **Documentation**: [gridpulse.network/docs](https://gridpulse.network/docs)
- **RapidAPI**: [rapidapi.com/devtee000/api/gridpulse-energy](https://rapidapi.com/devtee000/api/gridpulse-energy)
- **npm (MCP)**: [npmjs.com/package/gridpulse-mcp](https://www.npmjs.com/package/gridpulse-mcp)
- **Status**: [stats.uptimerobot.com/J5zSXoBKy5](https://stats.uptimerobot.com/J5zSXoBKy5)

---

## 🤖 MCP Support for AI Agents

GridPulse is MCP-native. Connect Claude Desktop, Cursor, VS Code, Claude Code, or any AI agent in seconds.

### Quick Start (no API key needed)

```bash
npx gridpulse-mcp
```

### Claude Desktop

No API key needed for Basic tier:

```json
{
  "mcpServers": {
    "gridpulse": {
      "command": "npx",
      "args": ["-y", "gridpulse-mcp"]
    }
  }
}
```

With API key ([get one here](https://rapidapi.com/devtee000/api/gridpulse-energy)):

```json
{
  "mcpServers": {
    "gridpulse": {
      "command": "npx",
      "args": ["-y", "gridpulse-mcp"],
      "env": {
        "GRIDPULSE_API_KEY": "your_key_here"
      }
    }
  }
}
```

Or connect directly via Streamable HTTP:

```json
{
  "mcpServers": {
    "gridpulse": {
      "url": "https://api.gridpulse.network/mcp",
      "headers": {
        "X-API-Key": "your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add gridpulse --command "npx" --args "-y,gridpulse-mcp"
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gridpulse": {
      "command": "npx",
      "args": ["-y", "gridpulse-mcp"],
      "env": {
        "GRIDPULSE_API_KEY": "your_key_here"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "gridpulse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gridpulse-mcp"],
      "env": {
        "GRIDPULSE_API_KEY": "your_key_here"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "gridpulse": {
      "command": "npx",
      "args": ["-y", "gridpulse-mcp"],
      "env": {
        "GRIDPULSE_API_KEY": "your_key_here"
      }
    }
  }
}
```

### Ask your AI assistant

- *"What is the current electricity price in Germany?"*
- *"Which European country has the cheapest electricity right now?"*
- *"Find the cheapest 4-hour window to charge my EV in Norway before 7am"*
- *"Compare the carbon intensity of Germany, France, and Norway"*
- *"What is Germany's gas storage level and what does it mean for prices?"*
- *"Find the greenest grid in Europe to run my batch job tonight"*
- *"What's the GB electricity market doing — is the system long or short?"*
- *"Schedule my workload across DE, FR, and NO — find the cheapest and greenest window before midnight"*

### Available MCP Tools (16)

| Tool | Description | Plan |
|------|-------------|------|
| `get_current_price` | Latest spot price for any zone | Basic |
| `get_day_ahead_prices` | Full hourly day-ahead price curve | Basic |
| `get_carbon_intensity` | Real-time carbon intensity (gCO₂/kWh) | Basic |
| `get_green_score` | 0-100 green score combining renewables and carbon | Basic |
| `get_supported_zones` | List all 41+ supported zone codes | Basic |
| `compare_prices` | Compare prices across up to 10 zones | Basic |
| `compare_carbon` | Compare carbon intensity across up to 10 zones | Basic |
| `compare_green` | Compare green scores across up to 10 zones | Basic |
| `get_gas_storage` | EU gas storage level and price risk signal | Basic |
| `get_global_carbon` | Monthly carbon intensity for 70+ countries | Basic |
| `get_gb_market` | GB day-ahead vs system price spread | Basic |
| `get_weather` | Wind, solar, temperature for any zone | Basic |
| `get_cheapest_window` | Cheapest N contiguous hours before deadline | Pro |
| `get_price_history` | Historical prices between two dates | Pro |
| `get_optimal_schedule` | Multi-zone ranking by price, carbon, or balanced | Pro |

---

## ⚡ Quick Start (REST API)

No API key needed for Basic tier:

```bash
# Current electricity price in Germany
curl "https://api.gridpulse.network/v1/prices/current?zone=DE"

# Carbon intensity in Great Britain
curl "https://api.gridpulse.network/v1/carbon/current?zone=GB"

# Compare prices across Europe — ranked cheapest first
curl "https://api.gridpulse.network/v1/compare/prices?zones=DE,FR,NO,SE,DK,AT,NL,BE,ES"

# Gas storage in Germany
curl "https://api.gridpulse.network/v1/fuels/gas-storage?country=DE"

# Carbon intensity for Japan (global coverage)
curl "https://api.gridpulse.network/v1/carbon/global?country=JP"

# GB market — day-ahead vs system price spread
curl "https://api.gridpulse.network/v1/prices/gb-market"

# Green score comparison across regions
curl "https://api.gridpulse.network/v1/compare/green?zones=DE,FR,NO,GB,CAISO"
```

With API key (Pro+):

```bash
# Price history
curl "https://api.gridpulse.network/v1/prices/history?zone=DE&from=2025-01-01&to=2025-01-31" \
  -H "X-API-Key: your_key_here"

# Generation mix
curl "https://api.gridpulse.network/v1/generation/current?zone=DE" \
  -H "X-API-Key: your_key_here"

# Price volatility analytics
curl "https://api.gridpulse.network/v1/analytics/volatility?zone=DE&days=30" \
  -H "X-API-Key: your_key_here"
```

---

## 📡 Live Coverage

| Region | Zones | Update Frequency |
|--------|-------|-----------------|
| Europe | DE, AT, FR, NL, BE, ES, NO, SE, DK + 16 more | Every 15-30 min |
| Great Britain | GB — day-ahead + system prices + interconnectors + wind forecast | Every 30 min |
| United States | CAISO, ERCOT, NYISO, PJM, SPP, MISO, ISONE | Every 5 min |
| Australia | AU-NSW, AU-QLD, AU-VIC, AU-SA, AU-TAS | Every 5 min |
| Global Carbon | 70+ countries worldwide | Monthly |

---

## 📋 Endpoints (48 total)

### 🟢 Basic — Free

| Endpoint | Description |
|----------|-------------|
| `GET /v1/prices/current` | Latest spot price for any zone |
| `GET /v1/prices/day-ahead` | Next 24-48h prices |
| `GET /v1/prices/gb-market` | GB day-ahead vs system price spread |
| `GET /v1/compare/prices` | Compare prices across up to 10 zones |
| `GET /v1/compare/carbon` | Compare carbon intensity across up to 10 zones |
| `GET /v1/compare/green` | Compare green scores across up to 10 zones |
| `GET /v1/carbon/current` | Real-time carbon intensity (gCO₂/kWh) |
| `GET /v1/carbon/forecast` | 48h carbon forecast (GB) |
| `GET /v1/carbon/global` | Monthly carbon for 70+ countries |
| `GET /v1/green/score` | 0-100 cleanliness score |
| `GET /v1/fuels/gas-storage` | EU gas storage levels |
| `GET /v1/fuels/gas-storage/history` | Historical gas storage |
| `GET /v1/fuels/lng` | LNG terminal data |
| `GET /v1/fuels/summary` | EU-wide gas market summary |
| `GET /v1/fuels/henry-hub` | Henry Hub gas prices |
| `GET /v1/fuels/carbon-price` | EU ETS carbon allowance prices |
| `GET /v1/weather/current` | Wind, solar, temperature |
| `GET /v1/weather/forecast` | 48h weather forecast |
| `GET /v1/zones` | All supported zone codes |
| `GET /v1/stats` | Database statistics |
| `GET /v1/plans` | Plan details and limits |

### 🔵 Pro — $29/month

Everything in Basic, plus:

| Endpoint | Description |
|----------|-------------|
| `GET /v1/prices/history` | Full price history with date range |
| `GET /v1/prices/cheapest` | Cheapest N-hour window finder |
| `GET /v1/prices/consumer` | Consumer retail prices DE/AT |
| `GET /v1/generation/current` | Generation mix by fuel type |
| `GET /v1/generation/forecast` | Wind and demand forecast |
| `GET /v1/fuels/henry-hub/history` | Full Henry Hub history |
| `GET /v1/fuels/carbon-price/history` | Full EUA carbon price history |
| `GET /v1/fuels/retail-prices` | US retail prices by state |
| `POST /v1/webhooks` | Create price/carbon alert |
| `GET /v1/webhooks` | List your webhooks |
| `DELETE /v1/webhooks/:id` | Delete a webhook |

### 🟣 Ultra — $99/month

Everything in Pro, plus:

| Endpoint | Description |
|----------|-------------|
| `GET /v1/analytics/volatility` | Price volatility metrics |
| `GET /v1/analytics/negative-prices` | Historical negative price events |
| `GET /v1/analytics/negative-risk` | Negative price probability score (0-100) |
| `GET /v1/analytics/correlation` | Zone price correlation |
| `GET /v1/analytics/peak-hours` | Peak demand patterns |
| `GET /v1/analytics/grid-stress` | Grid stress indicator |
| `GET /v1/analytics/carbon-optimal` | Optimal low-carbon scheduling windows |
| `GET /v1/fuels/winter-readiness` | Winter gas risk score |
| `GET /v1/fuels/gas-power-correlation` | Gas/power price correlation |
| `GET /v1/fuels/lng-dependency` | LNG import dependency score |

### ⚫ Mega — $299/month

Everything in Ultra, plus:

| Endpoint | Description |
|----------|-------------|
| `GET /v1/analytics/hydro` | Hydro reservoir analytics for NO, CH, AT, SE, FI |

---

## 🧪 Testing

```bash
# Run all tests
npm test

# Run API endpoint audit (71 tests)
npm run audit --workspace=@gridpulse/api

# Run specific workspace tests
npm test --workspace=@gridpulse/api
```

---

## 📦 MCP Package

The `apps/mcp-package/` directory contains the standalone npm MCP server published as `gridpulse-mcp`.

```bash
# Run without installing
npx gridpulse-mcp

# Install globally
npm install -g gridpulse-mcp

# With API key
GRIDPULSE_API_KEY=your_key npx gridpulse-mcp
```

Published at: [npmjs.com/package/gridpulse-mcp](https://www.npmjs.com/package/gridpulse-mcp)

---

## 🗺️ Roadmap

- [ ] Japan (JEPX) — 9 regional zones + national system price in JPY
- [ ] Price forecasting — 24-72h XGBoost model for DE, GB, NO
- [ ] Direct API key registration on gridpulse.network
- [ ] Python SDK
- [ ] JavaScript/TypeScript SDK
- [ ] Expanded US zone coverage

---

## 📄 License

MIT — see [LICENSE](LICENSE)

---

## 📧 Support

- **Email**: devtee000@gmail.com
- **Website**: [gridpulse.network](https://gridpulse.network)
- **Docs**: [gridpulse.network/docs](https://gridpulse.network/docs)
- **API Status**: [stats.uptimerobot.com/J5zSXoBKy5](https://stats.uptimerobot.com/J5zSXoBKy5)
- **RapidAPI**: [rapidapi.com/devtee000/api/gridpulse-energy](https://rapidapi.com/devtee000/api/gridpulse-energy)