Population Calculator

A web application that calculates how many people live within X minutes travel time from a selected location in Europe.

Tech Stack

• Frontend: Next.js 14+ (React + TypeScript), MapLibre GL JS, Tailwind CSS
• Backend: Python FastAPI
• Database: PostgreSQL + PostGIS

Data Sources

• Population Grid: Eurostat/GISCO Census grid 2021
• Isochrones: OpenRouteService (ORS) public API
• Map Tiles: OpenStreetMap

Prerequisites

• Node.js 18+ and npm/yarn
• Python 3.10+
• Docker and Docker Compose

Setup

1. Start Database

docker-compose up -d

This will start PostgreSQL with PostGIS extension.

2. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Create backend/.env:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/population_db
ORS_API_KEY=  # optional, public API works without key

Initialize database (creates tables and enables PostGIS):

python -m app.db.init_db

Run backend:

uvicorn app.main:app --reload --port 8000

Backend API will be available at http://localhost:8000 (docs at http://localhost:8000/docs)

3. Frontend Setup

cd frontend
npm install

Create frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

Run frontend:

npm run dev

Visit http://localhost:3000

Project Structure

.
├── backend/              # FastAPI backend
│   ├── app/
│   │   ├── main.py      # main application entry
│   │   ├── api/         # api endpoints
│   │   ├── db/          # database setup
│   │   └── services/    # business logic
│   └── requirements.txt
├── frontend/             # Next.js frontend
│   ├── src/
│   │   ├── app/         # app router pages
│   │   └── components/  # react components
│   └── package.json
└── docker-compose.yml    # database setup

Development Phases

• ✅ Phase 0: Basic skeleton - COMPLETE
• ✅ Phase 1: Isochrone generation via ORS API - COMPLETE
• Phase 2: Population grid data ingestion (next)
• Phase 3: Spatial intersection and calculation
• Phase 4: Frontend integration
• Phase 5: Optimization and caching

Current Status: Phase 1 Complete! ✅ | Phase 2 Ready 📊

Phase 1: Isochrone Generation ✅

The application now generates isochrones from any location using the OpenRouteService API.

What's working:

• Interactive map with location selection
• Isochrone visualization (blue shaded area on map)
• Support for walking, cycling, and driving modes
• Travel time range: 5-60 minutes
• Intelligent caching to reduce API calls

Try it:

1. Keep backend running (uvicorn app.main:app --reload)
2. In new terminal: cd frontend && npm install && npm run dev
3. Visit http://localhost:3000
4. Click any location, select mode/time, click "Calculate Population"
5. Watch the isochrone appear!

Phase 2: Data Ingestion (Next Step) 📊

Phase 2 loads the Eurostat population grid into the database.

Quick Start:

1. See PHASE2_INSTRUCTIONS.md for detailed steps
2. See backend/DATA_SOURCES.md for download links
3. Install dependencies: pip install geopandas pandas
4. Download data from GISCO
5. Run: python scripts/ingest_population_data.py --file path/to/data.gpkg

Or skip for now: I can implement Phase 3 with test data so you can see it working end-to-end!

See PHASE1_COMPLETE.md for Phase 1 technical details.

License

MIT