curl

All examples assume jq is installed for pretty-printing JSON. If not, remove the | jq portion.

Basic queries

Health check

curl -s https://api.fuelkenya.com/v1/health | jq

{
  "status": "healthy"
}

All available towns

curl -s https://api.fuelkenya.com/v1/towns | jq

Latest prices for all towns

curl -s https://api.fuelkenya.com/v1/prices/latest | jq

Latest prices for one town

curl -s "https://api.fuelkenya.com/v1/prices/latest?town=Mombasa" | jq

Price history — last 12 cycles for Nairobi

curl -s "https://api.fuelkenya.com/v1/prices?town=Nairobi&limit=12" | jq

Price history with date range

curl -s "https://api.fuelkenya.com/v1/prices?town=Nairobi&start_date=2025-01-01&end_date=2025-12-31" | jq

Filtering with jq

Extract only Super Petrol prices, sorted cheapest first

curl -s https://api.fuelkenya.com/v1/prices/latest \
  | jq '[.[] | {town, super_petrol}] | sort_by(.super_petrol)'

Find the cheapest town for diesel

curl -s https://api.fuelkenya.com/v1/prices/latest \
  | jq 'min_by(.diesel) | {town, diesel}'

Get all towns where petrol is below 210

curl -s https://api.fuelkenya.com/v1/prices/latest \
  | jq '[.[] | select(.super_petrol < 210) | {town, super_petrol}]'

Print just the current cycle date range

curl -s https://api.fuelkenya.com/v1/prices/latest \
  | jq -r 'first | "Valid \(.valid_from) to \(.valid_to)"'

Pagination

The default page size is 100. To walk through all records:

# Page 1
curl -s "https://api.fuelkenya.com/v1/prices?limit=100&offset=0" | jq length
 
# Page 2
curl -s "https://api.fuelkenya.com/v1/prices?limit=100&offset=100" | jq length
 
# Continue until result length < 100

Ingest CSV (admin)

curl -X POST https://api.fuelkenya.com/v1/ingest/csv \
  -H "Authorization: Bearer $INGEST_TOKEN" \
  -F "file=@epra_july_2026.csv" \
  | jq

Expected response:

{
  "status": "success",
  "records_processed": 224,
  "timestamp": "2026-07-15T08:00:00Z"
}

Shell script — export prices to CSV file

#!/usr/bin/env bash
set -euo pipefail
 
API="https://api.fuelkenya.com/v1"
OUTPUT="fuel_prices_$(date +%Y%m%d).csv"
 
echo "town,super_petrol,diesel,kerosene,valid_from,valid_to" > "$OUTPUT"
 
curl -s "${API}/prices/latest" | jq -r \
  '.[] | [.town, .super_petrol, .diesel, .kerosene, .valid_from, .valid_to] | @csv' \
  >> "$OUTPUT"
 
echo "Exported to $OUTPUT ($(wc -l < "$OUTPUT") rows)"

Shell script — check if prices have changed since last run

#!/usr/bin/env bash
CACHE_FILE="/tmp/fuelkenya_valid_from.txt"
CURRENT=$(curl -s "https://api.fuelkenya.com/v1/prices/latest" \
  | jq -r 'first.valid_from')
 
if [[ -f "$CACHE_FILE" ]]; then
  LAST=$(cat "$CACHE_FILE")
  if [[ "$CURRENT" != "$LAST" ]]; then
    echo "Prices updated! New cycle starts $CURRENT"
    echo "$CURRENT" > "$CACHE_FILE"
  else
    echo "No change. Still on cycle starting $CURRENT"
  fi
else
  echo "First run. Cycle: $CURRENT"
  echo "$CURRENT" > "$CACHE_FILE"
fi

Python