Developer Docs

SA Fuel Price API

Monthly South African fuel retail prices — 95 ULP, 93 ULP and Diesel, inland and coastal. Published by the DMRE on the first Wednesday of each month. Free to consume, no key needed for reads.

Free reads No key required South Africa v2.0 · TypeScript · D1

Base URL https://sa-fuel-api.guerillagardeningkzn.workers.dev

Start here

Quickstart

All GET endpoints are open — no API key, no sign-up. Just fetch.

// Latest prices
fetch('https://sa-fuel-api.guerillagardeningkzn.workers.dev/v1/prices/latest')
  .then(r => r.json())
  .then(d => console.log(d.data));

// Last 12 months
fetch('https://sa-fuel-api.guerillagardeningkzn.workers.dev/v1/prices?limit=12')
  .then(r => r.json())
  .then(d => console.log(d.data));

// Specific month
fetch('https://sa-fuel-api.guerillagardeningkzn.workers.dev/v1/prices/2026-05')
  .then(r => r.json())
  .then(d => console.log(d.data));

Authentication

API Key

Read endpoints (GET) are public. Write endpoints (POST, PUT) require an API key via the Authorization header.

fetch('/v1/prices', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: JSON.stringify({ ... })
});

Limits

Rate Limits

Read endpoints

100 requests per 15 minutes per IP. Standard headers returned on every response.

Write endpoints

20 requests per hour per IP. API key required in addition to rate limit.

Response format

JSON Envelope

All responses return JSON with a success flag. Successful responses include data. Errors include an error object with a code and message.

// Success
{
  "success": true,
  "data": {
    "month":      "2026-05",
    "monthLabel": "May 2026",
    "prices": {
      "petrol": { "p95Inland": 26.63, "p95Coastal": 25.76, "p93Inland": 26.52 },
      "diesel": {
      "d500Inland": 31.18, "d500Coastal": 30.30,
      "d50Inland":  31.39, "d50Coastal":  30.51
    }
    },
    "source":    "DMRE",
    "updatedAt": "2026-05-06T00:00:00.000Z"
  }
}

// Error
{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "No prices found for 2024-13." }
}

Endpoints

Quick Reference

Method	Path	Auth	Description
GET	/v1/prices	—	All months
GET	/v1/prices/latest	—	Current month
GET	/v1/prices/:month	—	Specific month
GET	/v1/prices/range	—	Date range
GET	/v1/stats	—	Aggregates
POST	/v1/prices	🔑	Add month
PUT	/v1/prices/:month	🔑	Update month

Endpoint detail

Endpoints

GET /v1/prices ▼

Returns all months, newest first. Paginate with limit and offset.

Param	Type	Default
`limit`	integer	50	optional · max 200
`offset`	integer	0	optional

GET /v1/prices?limit=12&offset=0

GET /v1/prices/latest ▼

Returns the most recent month only. No parameters.

GET /v1/prices/latest

GET /v1/prices/:month ▼

Returns prices for a specific month. Month must be in YYYY-MM format.

GET /v1/prices/2026-05
GET /v1/prices/2025-01

GET /v1/prices/range ▼

All months within an inclusive date range, returned in ascending order.

Param	Format
`from`	YYYY-MM	required
`to`	YYYY-MM	required

GET /v1/prices/range?from=2025-01&to=2025-12

GET /v1/stats ▼

Aggregate statistics across all months — min, max and average for 95 Inland and Diesel Inland.

GET /v1/stats

POST /v1/prices 🔑 key required ▼

Add a new month's prices. Returns 409 Conflict if the month already exists. All price fields validated by Zod — must be positive numbers.

Field	Type
`month`	YYYY-MM	required
`monthLabel`	string	required · e.g. "Jun 2026"
`p95i`	number	required · 95 ULP Inland
`p95c`	number	required · 95 ULP Coastal
`p93i`	number	required · 93 ULP Inland
`d500i`	number	required · Diesel 500ppm Inland
`d500c`	number	required · Diesel 500ppm Coastal
`d50i`	number	required · Diesel 50ppm Inland
`d50c`	number	required · Diesel 50ppm Coastal
`source`	string	optional · default "DMRE"

PUT /v1/prices/:month 🔑 key required ▼

Update one or more price fields for an existing month. Only supplied fields are updated — untouched fields are left unchanged via COALESCE.

PUT /v1/prices/2026-05
Authorization: Bearer YOUR_API_KEY

{ "p95i": 26.71 }

AI Integration

Remote MCP Server

This API is also available as a Remote MCP server — add it to Claude or any MCP-compatible AI assistant and ask about South African fuel prices in plain language.

MCP Endpoint

POST /mcp
JSON-RPC 2.0 · Protocol 2024-11-05

Discovery

GET /.well-known/mcp
Lists tools and capabilities

Add to Claude

In Claude → Settings → Integrations → Add MCP Server

Name: SA Fuel Price API
URL:  https://sa-fuel-api.guerillagardeningkzn.workers.dev/mcp

Then ask Claude things like:

"What is the current petrol price in Durban?"
"How much has diesel cost on average over the past year?"
"Compare fuel prices in January 2025 vs January 2026."
"What was the cheapest month for 95 ULP since 2024?"

Available Tools

TOOL get_latest_fuel_prices ▼

Returns the current month's prices for all fuel grades — 95 ULP, 93 ULP and Diesel (500ppm and 50ppm), inland and coastal. No parameters required.

TOOL get_fuel_prices_by_month ▼

Returns prices for a specific month.

Param	Type
`month`	YYYY-MM	required

TOOL get_fuel_price_range ▼

Returns all months in a date range — useful for trend analysis and period comparisons.

Param	Type
`from`	YYYY-MM	required
`to`	YYYY-MM	required

TOOL get_fuel_stats ▼

Returns historical min, max and average prices for 95 ULP Inland and Diesel 500ppm Inland across all available months. No parameters required.