A production-ready FastAPI service for querying Who's On First geographic data using PostGIS.

• 🌍 Geographic Hierarchy Resolution: Convert lat/lon coordinates to administrative hierarchies
• 🔍 Place Lookup: Query places by Who's On First ID
• 🚀 Production-Ready: Connection pooling, error handling, health checks
• ☁️ Cloud-Native: Containerized and ready for AWS deployment
• 📊 Spatial Indexing: Optimized PostGIS queries with spatial indexes

1. Start the services:

   docker-compose up -d

2. Import sample data:

   pip install -r requirements.txt
   python import_wof_data.py --regions US --placetypes locality neighbourhood

3. Access the API:

   • API: http://localhost:2000
   • Docs: http://localhost:2000/docs
   • Health: http://localhost:2000/health

See DEPLOYMENT_GUIDE.md for complete instructions.

Quick deploy:

cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your AWS settings
terraform init
terraform apply
cd ..
chmod +x scripts/deploy.sh
./scripts/deploy.sh

Resolve coordinates to geographic hierarchy.

Query Parameters:

• lat (float): Latitude (-90 to 90)
• lon (float): Longitude (-180 to 180)

Example:

curl "http://localhost:2000/api/v1/hierarchy?lat=37.7749&lon=-122.4194"

Response:

{
  "continent": {"id": 102191581, "name": "North America", "placetype": "continent"},
  "country": {"id": 85633793, "name": "United States", "placetype": "country"},
  "region": {"id": 85688637, "name": "California", "placetype": "region"},
  "locality": {"id": 85922583, "name": "San Francisco", "placetype": "locality"}
}

Get place details by Who's On First ID.

Example:

curl "http://localhost:2000/api/v1/place/85922583"

Health check with database connectivity test.

Example:

curl "http://localhost:2000/health"

📖 For complete API documentation, see API_DOCUMENTATION.md

.
├── main.py                     # FastAPI application
├── import_wof_data.py         # Data import script
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Container image
├── docker-compose.yml         # Local development setup
├── .env.example               # Environment configuration template
├── DEPLOYMENT_GUIDE.md        # Complete deployment guide
├── terraform/                 # Infrastructure as Code
│   ├── main.tf               # Main infrastructure
│   ├── apprunner.tf          # API service deployment
│   └── terraform.tfvars.example
└── scripts/
    └── deploy.sh             # Deployment automation

Environment variables (see .env.example):

• DB_HOST: PostgreSQL host
• DB_PORT: PostgreSQL port (default: 5432)
• DB_NAME: Database name (default: wof)
• DB_USER: Database username
• DB_PASS: Database password
• DB_MIN_CONNECTIONS: Min connection pool size (default: 1)
• DB_MAX_CONNECTIONS: Max connection pool size (default: 10)

The import_wof_data.py script downloads and imports Who's On First GeoJSON data.

Initial import (US data):

python import_wof_data.py --regions US --placetypes locality neighbourhood

Add new regions (safe, won't touch existing data):

python import_wof_data.py --regions CA GB FR --placetypes locality neighbourhood

Update existing data with latest WOF changes:

python import_wof_data.py --regions US CA GB FR --update

• INSERT mode (default): Adds new records, skips existing ones

  • Use for: Initial imports, adding new regions

• UPDATE mode (--update): Updates existing records + adds new ones

  • Use for: Refreshing data with latest changes from WOF

See DATA_MANAGEMENT.md for complete data import workflows and examples.

• FastAPI: Modern Python web framework
• PostgreSQL: Relational database
• PostGIS: Spatial database extension
• psycopg2: PostgreSQL adapter
• Shapely: Geometric operations
• Docker: Containerization
• Terraform: Infrastructure as Code
• AWS: Cloud platform (RDS, App Runner, ECR)

Approximate monthly costs on AWS:

• RDS db.t3.small (50GB): ~$35
• App Runner (1 vCPU, 2GB): ~$25
• Data transfer & storage: ~$10
• Total: ~$70/month

See DEPLOYMENT_GUIDE.md for cost optimization tips.

Run tests:

# TODO: Add tests
pytest

Format code:

black main.py import_wof_data.py

Type checking:

mypy main.py

• API_DOCUMENTATION.md - Complete API reference with examples
• DEPLOYMENT_GUIDE.md - Complete deployment instructions
• DATA_MANAGEMENT.md - Data import and management guide
• WOF_CLOUD_SETUP.md - Cloud setup background
• CLOUD_DEPLOYMENT_GUIDANCE.md - AWS specifics

• Who's On First - Project website
• WOF Data - Data repository
• PostGIS - Spatial database
• FastAPI - Web framework

See Who's On First licensing at: https://www.whosonfirst.org/docs/licenses/

For issues or questions:

1. Check DEPLOYMENT_GUIDE.md troubleshooting section
2. Review WOF documentation
3. Check application logs and CloudWatch metrics

Made with ❤️ using Who's On First data