# Berlin Picnic Zone Finder API

Find the perfect picnic zones in Berlin based on your personality and preferences.

## 🚀 Quick Start

### Prerequisites
- Python 3.11+
- [uv](https://github.com/astral-sh/uv) package manager

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/berlin-picnic-api.git
cd berlin-picnic-api

# Install dependencies
uv sync --dev

# Create environment file
cp .env.example .env

# Start the development server
uv run uvicorn app.main:app --reload
```

The API will be available at `http://localhost:8000`

## 📚 API Documentation

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

## 🏗️ Project Structure

```
app/
├── main.py              # FastAPI application
├── config.py            # Configuration settings
├── models/              # Pydantic models
├── services/            # Business logic
├── utils/               # Utility functions
├── routers/             # API route handlers
└── data/                # Data storage
```

## 🔧 Development

### Code Quality

```bash
# Format code
uv run ruff format .

# Lint code
uv run ruff check . --fix

# Type checking
uv run mypy app/

# Run tests
uv run pytest

# Run all checks
uv run ruff check . && uv run ruff format . && uv run mypy app/ && uv run pytest
```

### Data Management

```bash
# Fetch Berlin open data
uv run python scripts/fetch_berlin_data.py

# Process zone data
uv run python scripts/process_zones.py
```

## 🌍 API Endpoints

### Zones

- `GET /zones` - Get zones filtered by personality and preferences
- `GET /zones/{zone_id}` - Get specific zone details
- `GET /zones/{zone_id}/scores` - Get personality scores for a zone

### Neighborhoods

- `GET /neighborhoods` - Get all Berlin neighborhoods

### Health

- `GET /health` - Basic health check
- `GET /health/ready` - Readiness check

## 🎯 Personality Types

- `little_adventurers` - Families with kids
- `date_night` - Romantic couples
- `squad_goals` - Friend groups
- `zen_masters` - Peace seekers
- `active_lifestyle` - Fitness enthusiasts
- `wildlife_lover` - Nature enthusiasts
- `art_nerd` - Art and culture lovers
- `history_geek` - History enthusiasts

## 🗺️ Berlin Neighborhoods

- Mitte, Kreuzberg, Friedrichshain, Prenzlauer Berg
- Charlottenburg, Wilmersdorf, Schöneberg, Tempelhof
- Neukölln, Pankow, Wedding, Moabit

## 📊 Scoring Factors

- Tree coverage and shade
- Noise levels
- Wildlife diversity
- Nearby amenities (Späti, restaurants, toilets)
- Playgrounds and water features
- Public transport accessibility
- Fitness facilities and paths

## 🚀 Deployment

### Docker

```bash
# Build image
docker build -t berlin-picnic-api .

# Run container
docker run -p 8000:8000 berlin-picnic-api
```

### Docker Compose

```bash
# Start all services
docker-compose up -d
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 📞 Support

- GitHub Issues: [Create an issue](https://github.com/yourusername/berlin-picnic-api/issues)
- Email: your.email@example.com