jhembe/tz-fuel-api

Tanzania fuel price REST API — scrapes EWURA bulletins (2009–present), time-series ML forecasting (ARIMA/SARIMA/Holt-Winters), K-means district clustering, 185 districts # Tanzania Fuel Price API A production-grade REST API that scrapes **EWURA** (Energy and Water Utilities Regulatory Authority) monthly PDF bulletins and serves Tanzania's official fuel cap prices as clean, structured data — covering petrol, diesel, and kerosene across all mainland and Zanzibar districts since 2009. Live at **fuelapi.mahembega.com** Dashboard at **fuel.mahembega.com** --- ## Screenshots | Overview | Price Map | |---|---| | | | | Deep Analytics | EWURA Bulletins | |---|---| | | | | Historical Trends | Mobile | |---|---| | | | --- ## Features - **19,900+ fuel price records** from 131 pricing periods (2009–present) - **190 districts** across mainland Tanzania and Zanzibar - **Monthly PDF scraping** from EWURA's official website - **Automated scheduling** — new prices fetched on the 6th of each month - **Multi-model forecasting** — auto-selects best model (Holt-Winters ETS, ARIMA, SARIMA, SARIMAX-X with oil cost in TZS) - **Brent crude integration** — 200+ months of oil price history via EIA API - **TZS/USD exchange rate history** — full rate history back to 1960, auto-synced monthly; used as a combined exogenous variable (`brent × TZS/USD`) in SARIMAX-X - **PDF hosting** — bulletins stored and served locally; no EWURA URL dependency for end users - **8 analytics endpoints** — volatility, inflation, regional gap, correlation, forecast, peak records, exchange rate - Rate-limited, cached, and production-ready --- ## API Endpoints ### Core | Method | Path | Description | |---|---|---| | `GET` | `/api/v1/prices/latest` | Latest fuel prices for all districts | | `GET` | `/api/v1/prices/district/{name}/history` | Full price history for one district | | `GET` | `/api/v1/stats` | National averages (min/max/cheapest/dearest) | | `GET` | `/api/v1/search` | Search districts by name | | `GET` | `/api/v1/compare` | Side-by-side comparison (up to 3 districts) | | `GET` | `/api/v1/cheapest` | Cheapest districts for a fuel type | | `GET` | `/ap …