Name: SA Fuel Price API - Official South African Petrol and Diesel Prices
Brand: evanvandalen
SKU: api-evanvandalen-sa-fuel-price
Availability: InStock
Author: API Market

# South Africa Fuel Price API

Official South African fuel pump prices sourced from the Department of Mineral Resources and Petroleum (DMRE). Get current and historical prices for Petrol 93 ULP, Petrol 95 ULP, and Diesel 50ppm for both inland and coastal regions. Prices are updated automatically every Wednesday at 08:00 SAST.

## Overview

South Africa's fuel prices are regulated by the government and announced on the first Wednesday of every month. Tracking these prices means monitoring government press releases, scraping inconsistent PDF documents, and maintaining your own data pipeline. This API eliminates all of that — one endpoint call returns clean, structured JSON with the latest official prices.

**Fuel Types:** petrol_93, petrol_95, diesel_50ppm

**Regions:** inland (Gauteng and surrounding provinces), coastal (Western Cape, KwaZulu-Natal, Eastern Cape)

**Historical Coverage:** January 2008 to present — over 18 years of South African fuel price data.

## Features

- **8 Dedicated Endpoints**: Get current prices, single fuel type lookups, full history, specific month lookups, trend analysis, price comparison, next update date, and a health check.
- **18 Years of History**: Price data from January 2008 to present covering all fuel types and both regions.
- **Month-on-Month Change**: The /trend endpoint includes ZAR and percentage change values for every month returned.
- **Price Comparison**: Compare any two months and get the absolute and percentage change between them.
- **Auto-Updated**: Prices are scraped and upserted automatically every Wednesday at 08:00 SAST — no stale data.
- **Consistent Response Envelope**: Every endpoint returns the same success/data/meta JSON structure for predictable integration.

## Use Cases

- **Fleet Management** — calculate monthly fuel costs across vehicle fleets using accurate official pump prices
- **Logistics and Transport** — build accurate route cost estimators and delivery budgeting tools
- **Personal Finance Apps** — show users how much they are spending on fuel and how prices have changed over time
- **Property and Affordability Calculators** — factor in commuting fuel costs as part of monthly expense calculations
- **Business Expense Tracking** — automate fuel expense reimbursement based on official pump prices
- **Academic and Economic Research** — analyse the impact of fuel price changes on inflation and household budgets
- **Dashboards and Data Visualisations** — build price trend charts and year-on-year comparisons for reporting tools

## API Documentation

### Base URL

All API requests for the SA Fuel Price API should be made to the following base URL:

```
https://prod.api.market/v1/evanvandalen/sa-fuel-price
```

### Authentication

Authentication is handled via a unified API key shared across all APIs on the platform. Include your key in the `x-api-market-key` header of every request:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

---

### Endpoints

#### 1. Get Latest Prices

Returns the current month's official pump prices for all fuel types and both regions in a single response. The fastest way to display a live fuel price board in your application.

**Method**: `GET`
**Endpoint**: `/latest`

No parameters required.

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/latest" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": {
    "year": 2026,
    "month": 6,
    "prices": {
      "petrol_93": { "inland": 27.95, "coastal": 27.16 },
      "petrol_95": { "inland": 28.06, "coastal": 27.19 },
      "diesel_50ppm": { "inland": 29.26, "coastal": 28.00 }
    }
  },
  "meta": {
    "effective_date": "2026-06-04",
    "next_update": "2026-07-01",
    "cached": false
  }
}
```

---

#### 2. Get Latest Price — Single Fuel Type

Returns the current month's price for a single fuel type and region. Use this when your app only needs one specific value.

**Method**: `GET`
**Endpoint**: `/latest/{fuel_type}/{region}`

**Parameters**:

| Name | In | Description | Type | Required |
|:-----|:---|:------------|:-----|:---------|
| `fuel_type` | path | The fuel type to retrieve. Accepted values: `petrol_93`, `petrol_95`, `diesel_50ppm`, `paraffin` | string | Yes |
| `region` | path | The region to retrieve prices for. Accepted values: `inland`, `coastal` | string | Yes |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/latest/petrol_95/inland" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": {
    "year": 2026,
    "month": 6,
    "fuel_type": "petrol_95",
    "region": "inland",
    "price_zar": 28.06,
    "effective_date": "2026-06-04"
  },
  "meta": {
    "next_update": "2026-07-01",
    "cached": false
  }
}
```

---

#### 3. Get Price History

Returns the full historical price record from January 2008 to present, newest first. Filter by fuel type and region using optional query parameters.

**Method**: `GET`
**Endpoint**: `/history`

**Parameters**:

| Name | In | Description | Type | Required |
|:-----|:---|:------------|:-----|:---------|
| `fuel_type` | query | Filter by fuel type. Accepted values: `petrol_93`, `petrol_95`, `diesel_50ppm`, `paraffin` | string | No |
| `region` | query | Filter by region. Accepted values: `inland`, `coastal` | string | No |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/history?fuel_type=petrol_95&region=inland" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": [
    {
      "year": 2026,
      "month": 6,
      "fuel_type": "petrol_95",
      "region": "inland",
      "price_zar": 28.06,
      "effective_date": "2026-06-04"
    },
    {
      "year": 2026,
      "month": 5,
      "fuel_type": "petrol_95",
      "region": "inland",
      "price_zar": 26.63,
      "effective_date": "2026-05-06"
    }
  ],
  "meta": {
    "count": 217,
    "filters": { "fuel_type": "petrol_95", "region": "inland" },
    "next_update": "2026-07-01",
    "cached": false
  }
}
```

---

#### 4. Get Price by Month

Returns all fuel prices for a specific month and year. Returns a 404 if no data exists for the requested period.

**Method**: `GET`
**Endpoint**: `/month/{year}/{month}`

**Parameters**:

| Name | In | Description | Type | Required |
|:-----|:---|:------------|:-----|:---------|
| `year` | path | The year to retrieve prices for. Must be a 4-digit year between 2008 and the current year | string | Yes |
| `month` | path | The month to retrieve prices for. Must be a number between 1 and 12 | string | Yes |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/month/2024/3" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": {
    "year": 2024,
    "month": 3,
    "prices": {
      "petrol_93": { "inland": 24.13, "coastal": 23.41 },
      "petrol_95": { "inland": 24.45, "coastal": 23.73 },
      "diesel_50ppm": { "inland": 22.62, "coastal": 21.93 }
    }
  },
  "meta": {
    "effective_date": "2024-03-06",
    "next_update": "2024-04-03",
    "cached": false
  }
}
```

---

#### 5. Get Price Trend

Returns the last N months of prices for a single fuel type and region with month-on-month change values in ZAR and percentage. The oldest record in the result will have null change values as there is no prior month to compare against.

**Method**: `GET`
**Endpoint**: `/trend`

**Parameters**:

| Name | In | Description | Type | Required |
|:-----|:---|:------------|:-----|:---------|
| `fuel_type` | query | The fuel type to retrieve trend data for. Accepted values: `petrol_93`, `petrol_95`, `diesel_50ppm`, `paraffin` | string | Yes |
| `region` | query | The region to retrieve trend data for. Accepted values: `inland`, `coastal` | string | Yes |
| `months` | query | Number of months to return. Must be between 1 and 60. Defaults to 12 if not provided | string | No |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/trend?fuel_type=petrol_95&region=inland&months=3" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": [
    {
      "year": 2026,
      "month": 6,
      "price_zar": 28.06,
      "effective_date": "2026-06-04",
      "change_zar": 1.43,
      "change_pct": 5.37
    },
    {
      "year": 2026,
      "month": 5,
      "price_zar": 26.63,
      "effective_date": "2026-05-06",
      "change_zar": 3.27,
      "change_pct": 14.0
    },
    {
      "year": 2026,
      "month": 4,
      "price_zar": 23.36,
      "effective_date": "2026-04-01",
      "change_zar": null,
      "change_pct": null
    }
  ],
  "meta": {
    "fuel_type": "petrol_95",
    "region": "inland",
    "months": 3,
    "cached": false
  }
}
```

---

#### 6. Compare Prices Between Two Months

Compares the price of a fuel type and region between any two months. Returns the price at both points plus the absolute ZAR change and percentage change.

**Method**: `GET`
**Endpoint**: `/compare`

**Parameters**:

| Name | In | Description | Type | Required |
|:-----|:---|:------------|:-----|:---------|
| `fuel_type` | query | The fuel type to compare. Accepted values: `petrol_93`, `petrol_95`, `diesel_50ppm`, `paraffin` | string | Yes |
| `region` | query | The region to compare prices for. Accepted values: `inland`, `coastal` | string | Yes |
| `from` | query | The start month for comparison in YYYY-MM format. Example: 2020-01 | string | Yes |
| `to` | query | The end month for comparison in YYYY-MM format. Example: 2026-06 | string | Yes |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/compare?fuel_type=petrol_95&region=inland&from=2020-01&to=2026-06" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": {
    "fuel_type": "petrol_95",
    "region": "inland",
    "from": {
      "year": 2020,
      "month": 1,
      "price_zar": 16.16,
      "effective_date": "2020-01-01"
    },
    "to": {
      "year": 2026,
      "month": 6,
      "price_zar": 28.06,
      "effective_date": "2026-06-04"
    },
    "change_zar": 11.90,
    "change_pct": 73.64
  },
  "meta": {
    "cached": false
  }
}
```

---

#### 7. Get Next Update Date

Returns the next expected DMRE fuel price announcement date and the number of days remaining until that date.

**Method**: `GET`
**Endpoint**: `/next-update`

No parameters required.

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/next-update" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": {
    "next_update": "2026-07-01",
    "days_until": 27
  },
  "meta": {
    "cached": false
  }
}
```

---

#### 8. Health Check

Returns the current operational status of the API and a server timestamp. Use for uptime monitoring and pre-flight checks.

**Method**: `GET`
**Endpoint**: `/health`

No parameters required.

**Example Request**:

```bash
curl -X GET "https://prod.api.market/v1/evanvandalen/sa-fuel-price/health" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "success": true,
  "data": {
    "status": "ok",
    "timestamp": "2026-06-05T08:00:00.000Z"
  }
}
```

---

## Response Format

All endpoints return a consistent JSON envelope:

```json
{
  "success": true,
  "data": { },
  "meta": {
    "effective_date": "2026-06-04",
    "next_update": "2026-07-01",
    "cached": false
  }
}
```

All errors return:

```json
{
  "error": true,
  "code": "BAD_REQUEST",
  "message": "Invalid fuel_type. Valid values: petrol_93, petrol_95, diesel_50ppm, paraffin"
}
```

---

## Status Codes

| Code | Status | Description |
|:-----|:-------|:------------|
| `200` | OK | The request succeeded and data has been returned. |
| `400` | Bad Request | The request contains invalid or missing parameters. Review the parameter table for the endpoint. |
| `401` | Unauthorized | The `x-api-market-key` header is missing or contains an invalid key. |
| `403` | Forbidden | Your API key is valid but lacks permission to access this resource. |
| `404` | Not Found | No data exists for the requested month and year combination. |
| `429` | Too Many Requests | You have exceeded the rate limit. Implement exponential backoff and retry. |
| `500` | Internal Server Error | An unexpected server-side error occurred. Retry the request after a brief delay. |
| `503` | Service Unavailable | The server is temporarily unavailable. Retry after a short delay. |

---

## Price Updates

Prices are updated automatically every Wednesday at 08:00 SAST. The DMRE announces new pump prices on the first Wednesday of each month. If a mid-month price adjustment occurs due to significant oil price or exchange rate movements, it will be reflected on the following Wednesday.

---

## FAQ

**How often are prices updated?**
Prices are updated every Wednesday at 08:00 SAST. The DMRE announces new pump prices on the first Wednesday of each month. The cron job runs three times every Wednesday (08:00, 12:00, 18:00) to catch delayed announcements.

**How far back does the historical data go?**
Historical data is available from January 2008 to present — over 18 years of South African fuel price records.

**What fuel types are covered?**
Petrol 93 ULP, Petrol 95 ULP, and Diesel 50ppm for both inland and coastal regions. The paraffin fuel type exists in the schema but data is not currently available from the source.

**What is the difference between inland and coastal prices?**
The DMRE sets different pump prices for inland and coastal regions due to transportation and logistics cost differences. Inland prices apply to Gauteng and surrounding provinces. Coastal prices apply to the Western Cape, KwaZulu-Natal, and Eastern Cape.

**What currency are prices returned in?**
All prices are returned in ZAR (South African Rand) per litre.

**Are there any months with missing data?**
Five months are missing from the dataset due to gaps in the source data: July 2011, December 2014, February 2015, July 2015, and September 2021. Requesting these months via `/month/{year}/{month}` will return a 404.

**What is the difference between /latest and /latest/{fuel_type}/{region}?**
`/latest` returns all fuel types and both regions in a single nested response — useful when you need the full price board. `/latest/{fuel_type}/{region}` returns a single price for one specific combination — useful when your app only needs one value and you want a smaller, faster response.

**How do I calculate the percentage price increase over time?**
Use the `/compare` endpoint. Pass your fuel type, region, a `from` month and a `to` month in YYYY-MM format and the API returns the price at both points plus the change in ZAR and as a percentage.

**How do I authenticate?**
Include your API key in the `x-api-market-key` request header on every call.

**What data source does this API use?**
Prices are sourced from the AA South Africa fuel pricing data, which reflects official DMRE monthly announcements. The DMRE (Department of Mineral Resources and Petroleum) is the South African government department responsible for regulating fuel prices under the Petroleum Products Act.

---

## Support

For questions or issues contact evan@van-dalen.dev

Get official South African fuel prices for Petrol 93, Petrol 95, and Diesel 50ppm. Inland and coastal regions. Historical data from 2008. Auto-updated monthly from DMRE.

SA Fuel Price API - Official South African Petrol and Diesel Prices

Free