FuelSpyder

FuelSpyder is a production-grade FastAPI application that aggregates real-time UK fuel price data from major retailers, providing a unified REST API for querying cheapest and cleanest fuel options by location.

Features

• Concurrent Data Fetching: Async HTTP with httpx and asyncio.gather() for fast aggregation
• Normalized Data Format: Standardized schema across all providers
• Smart Caching: In-memory cache with configurable TTL (5 min default)
• Environmental Ratings: Fuel cleanliness ranking based on UK carbon intensity standards
• Robust Error Handling: Graceful degradation when providers fail
• Production Ready: Structured logging, health checks, Docker support

Supported Retailers

Currently Implemented:

• Asda

Planned (Phase 2):

• BP, Esso, Morrisons, Moto, Motor Fuel Group, Rontec, Sainsbury's, SGN, Shell, Tesco

API Endpoints

Get All Prices

GET /api/v1/prices

Fetches from all providers concurrently. Returns normalized station data with prices.

Get Provider Prices

GET /api/v1/prices/{provider}

Fetches from a specific provider (e.g., /api/v1/prices/asda).

List Providers

GET /api/v1/prices/providers/list

Returns all available provider names.

Health Check

GET /api/v1/health

Health status for monitoring/orchestration.

Quick Start

Local Development

1. Clone the repository:

   git clone https://github.com/CodeKeanu/fuelspyder.git
   cd fuelspyder

2. Install dependencies:

   pip install -r requirements.txt

3. Run the app:

   python -m app.main
   # Or with auto-reload:
   uvicorn app.main:app --reload

4. Access the API:

   • Visit http://localhost:8000 (redirects to docs)
   • Interactive docs at http://localhost:8000/docs
   • Alternative docs at http://localhost:8000/redoc

Docker Deployment

1. Build the image:

   docker build -t fuelspyder:latest .

2. Run the container:

   docker run -d -p 8000:8000 --name fuelspyder fuelspyder:latest

3. Access the API:

   • http://localhost:8000/docs

Example Usage

Fetch all providers

curl http://localhost:8000/api/v1/prices

Fetch specific provider

curl http://localhost:8000/api/v1/prices/asda

List available providers

curl http://localhost:8000/api/v1/prices/providers/list

Configuration

Copy .env.example to .env and adjust settings:

cp .env.example .env

Key settings:

• CACHE_TTL_SECONDS: Cache duration (default: 300s)
• HTTP_TIMEOUT: Provider request timeout (default: 10s)
• LOG_LEVEL: Logging level (default: INFO)

Architecture

app/
├── main.py              # FastAPI application
├── config.py            # Settings management
├── api/v1/
│   ├── router.py        # API router aggregation
│   └── endpoints/       # API endpoints
├── schemas/             # Pydantic models
├── services/            # Business logic
│   ├── aggregator.py    # Concurrent fetching
│   ├── http_client.py   # Async HTTP
│   └── cache.py         # In-memory caching
├── providers/           # Provider adapters
│   ├── base.py          # Abstract base
│   ├── registry.py      # Provider registry
│   └── asda.py          # Asda implementation
└── core/                # Core utilities
    ├── exceptions.py    # Custom exceptions
    └── logging.py       # Logging config

License

MIT License

---

Note: This project simply proxies public data from retailer APIs. Data accuracy and availability depend on the source sites.