# Weather Dashboard API

A powerful API for retrieving weather data, forecasts, and managing location bookmarks, built with FastAPI and SQLite.

## Features

- **User Authentication**: Secure JWT-based authentication
- **Current Weather Data**: Get real-time weather information for any location
- **Weather Forecasts**: Access 5-day weather forecasts
- **Location Bookmarking**: Save and manage your favorite locations
- **Default Location**: Set a default location for quick weather checks
- **Caching**: Efficient caching to minimize external API calls
- **OpenAPI Documentation**: Auto-generated, interactive API documentation

## Tech Stack

- **Framework**: FastAPI
- **Database**: SQLite with SQLAlchemy ORM
- **Migrations**: Alembic
- **Authentication**: JWT with OAuth2
- **Password Hashing**: Bcrypt
- **HTTP Client**: HTTPX
- **External API**: OpenWeatherMap API
- **Documentation**: Swagger UI / ReDoc

## Prerequisites

- Python 3.8+
- OpenWeatherMap API key (free tier available)

## Environment Variables

Create a `.env` file in the root directory with the following variables:

```
OPENWEATHER_API_KEY=your_api_key_here
SECRET_KEY=your_secret_key_here
```

## Installation

1. Clone the repository:

```bash
git clone https://github.com/yourusername/weather-dashboard-api.git
cd weather-dashboard-api
```

2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Set up the database:

```bash
alembic upgrade head
```

## Running the Application

Start the development server:

```bash
uvicorn main:app --reload
```

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

## API Documentation

Interactive API documentation is available at:

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

## API Endpoints

### Authentication

- `POST /api/v1/users/register` - Register a new user
- `POST /api/v1/users/login` - Login and get access token
- `GET /api/v1/users/me` - Get current user information

### Weather Data

- `GET /api/v1/weather/current` - Get current weather for specific coordinates
- `GET /api/v1/weather/current/default` - Get current weather for default location
- `GET /api/v1/weather/forecast` - Get 5-day forecast for specific coordinates
- `GET /api/v1/weather/forecast/default` - Get 5-day forecast for default location

### Location Management

- `GET /api/v1/locations` - Get all saved locations
- `GET /api/v1/locations/default` - Get default location
- `POST /api/v1/locations` - Create a new location
- `GET /api/v1/locations/{location_id}` - Get a specific location
- `PUT /api/v1/locations/{location_id}` - Update a specific location
- `DELETE /api/v1/locations/{location_id}` - Delete a specific location

### Health Check

- `GET /health` - Check API health status

## Database Models

### User

- ID
- Email (unique)
- Username (unique)
- Hashed Password
- Is Active
- Is Superuser
- Created At
- Updated At
- Relationships: Locations

### Location

- ID
- Name
- Latitude
- Longitude
- Country (optional)
- Is Default
- Created At
- Updated At
- User ID (foreign key)
- Relationships: User

## Project Structure

```
weather-dashboard-api/
├── alembic.ini                # Alembic configuration
├── main.py                    # FastAPI application entry point
├── requirements.txt           # Python dependencies
├── app/                       # Application package
│   ├── api/                   # API endpoints
│   │   ├── deps.py            # API dependencies
│   │   └── v1/                # API version 1
│   │       ├── endpoints/     # API route handlers
│   │       └── router.py      # API router
│   ├── core/                  # Core functionality
│   │   ├── config.py          # App configuration
│   │   └── security.py        # Security utilities
│   ├── crud/                  # CRUD operations
│   ├── db/                    # Database setup
│   │   └── session.py         # DB session
│   ├── models/                # SQLAlchemy models
│   ├── schemas/               # Pydantic schemas
│   └── services/              # Business logic services
│       ├── cache_service.py   # Caching service
│       └── weather_service.py # Weather API client
└── migrations/                # Alembic migrations
    ├── env.py                 # Migration environment
    ├── script.py.mako         # Migration template
    └── versions/              # Migration scripts
```

## Error Handling

The API includes comprehensive error handling:

- Invalid input validation
- Authentication and authorization errors
- Resource not found errors
- External API communication errors
- Rate limiting and caching errors

## Caching Strategy

The API implements a simple in-memory caching strategy to minimize calls to the OpenWeatherMap API:

- Cache duration is configurable (default: 5 minutes)
- Separate cache keys for current weather and forecasts
- Automatic cache invalidation on expiration

## Development

To contribute to this project:

1. Create a feature branch:
```bash
git checkout -b feature/your-feature-name
```

2. Make your changes and run tests:
```bash
pytest
```

3. Run code linting:
```bash
ruff check --fix
```

4. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgements

- [FastAPI](https://fastapi.tiangolo.com/)
- [SQLAlchemy](https://www.sqlalchemy.org/)
- [Alembic](https://alembic.sqlalchemy.org/)
- [OpenWeatherMap API](https://openweathermap.org/api)