bagoviggo/shamba-price-api

An API that provides regional market information for agricultural produce across Kenyan markets in 47 counties # Shamba AI — FastAPI Backend Real-time Kenyan agricultural commodity price API, scraped daily from KAMIS. ## Stack - **FastAPI** — async Python web framework - **PostgreSQL** — price records storage - **Redis** — response caching - **SQLAlchemy (async)** — ORM + query layer - **Alembic** — database migrations - **APScheduler** — daily 6 AM scrape cron - **httpx + BeautifulSoup** — KAMIS HTML scraper --- ## Quick Start (Local) ### 1. Prerequisites - Python 3.11+ - Docker Desktop (for Postgres + Redis) ### 2. Clone & install ```bash git clone cd shamba-api python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt ``` ### 3. Start databases ```bash docker-compose up -d # Postgres on :5432, Redis on :6379 ``` ### 4. Configure environment ```bash cp .env.example .env # Edit .env — at minimum set ANTHROPIC_API_KEY if you're using the AI endpoints ``` ### 5. Run database migrations ```bash alembic upgrade head ``` ### 6. Start the API ```bash uvicorn app.main:app --reload ``` API is live at **http://localhost:8000** Swagger docs at **localhost --- ## Seed Data (First Run) Trigger the scraper manually to populate the database: ```bash curl -X POST localhost ``` This fetches the latest KAMIS data. Takes 10–30 seconds depending on how many pages need to be fetched. Check progress: ```bash curl localhost ``` --- ## API Reference ### Health ``` GET /health ``` ### Prices ``` GET /api/v1/prices ?commodity=Tomatoes &county=Nairobi &market=Gikomba &date_from=2026-03-01 &date_to=2026-03-09 &page=1 &limit=50 GET /api/v1/prices/daily ?county=Nakuru ?commodity=Dry+Maize GET /api/v1/prices/commodity/{name}/trend ?days=30 GET /api/v1/prices/compare ?commodity=Tomatoes &counties=Nairobi,Nakuru,Eldoret &days=7 GET /api/v1/prices/movers ?limit=10 ``` ### Commodities ``` GET /api/v1/commodities GET /api/v1/commodities/{name} …