Earlier this year I visited Bouche in Brussels, Belgium and it completely changed what I thought a coffee shop could be. The beans were a house blend, but the quality was on another level. The interior, the merch, the whole vibe: "I was hooked".
That trip sent me down a rabbit hole. I discovered The World's 100 Best Coffee Shops, an annual ranking published every February at a global coffee festival. They release two lists: a Top 100 Global and a Top 100 South America edition. Bouche made it at #75.
I built ROAST. to make that data actually explorable.
Whether you're on a work trip, traveling, on vacation, or just visiting someone;
Whenever the coffee vibes hit, you can open ROAST. and instantly see if one of the world's best coffee shops is near you! Why not?!
The site features:
- Interactive world map with country-level shop density bubbles
- Drill-down to individual shop details (address, city, country, rank)
- Filterable list view by collection, country, and rank band
- Public Google Maps links — no API key required for visitors
A zero-cost, open-source pipeline that:
- Scrapes the annual Top 100 + South America rankings from theworlds100bestcoffeeshops.com
- Enriches each shop entry with city, address, and geocoordinates
- Generates
JSON,CSV, andKMLartifacts - Builds a static site and auto-deploys via GitHub Pages
- Runs automatically on a CI/CD schedule via GitHub Actions
| Layer | Technology |
|---|---|
| Language | Python 3.11+ |
| Preview UI | FastAPI + Jinja2 |
| Site Builder | Static HTML/CSS generator |
| Maps | Public Google Maps links (zero API cost) |
| Testing | pytest (21 tests passing) |
| CI/CD | GitHub Actions → GitHub Pages |
Top-100-Best-CoffeeShops/
├── src/ # Scraper, enricher, site builder
├── data/ # current_list.json (source of truth)
├── output/ # coffee_shops.csv, coffee_shops.kml
├── site/ # Generated static site (index.html + assets)
├── templates/ # Jinja2 HTML templates
├── tests/ # pytest test suite
├── claude_prompts/ # AI prompts used during development
├── docs/ # Release timeline and notes
└── .github/workflows/ # CI/CD automation
This project runs entirely for free:
- Visitors never need a Google API key — all map links are plain Google Maps URLs
- CI handles scraping, building, and deploying automatically
- Optional: Owner-only geocoding refresh via CLI (uses Google Places API once annually)
# Install dependencies
pip install -e .
# Run full pipeline (scrape → enrich → build)
python main.py
# Preview UI
uvicorn src.app:app --reload
# Run tests
pytestUse the standardized delivery framework in:
docs/development-framework.md
Use the helper command for repeatable gates:
# Verify targeted + full tests
scripts/dev-framework.sh verify
# Full pre-push gate (tests + build-site + diff review)
scripts/dev-framework.sh prepush
# Trigger deployment workflow after merge
scripts/dev-framework.sh workflow update_map.yml mainOn every push to main, GitHub Actions will:
- Run the test suite
- Execute the scrape + build pipeline
- Commit generated artifacts back to the repo
- Deploy to GitHub Pages
- Open a reminder issue if an owner geocode refresh is needed
- Source site uses Elementor — selectors may shift when the site redesigns
- Detail-page scraping is intentionally throttled (respectful crawl speed)
- Place ID completeness depends on annual owner geocode refresh
All coffee shop data sourced from theworlds100bestcoffeeshops.com — an independent annual ranking published each February.
Built by @YFC-ophey · Buy Me a Coffee