https://github.com/dax-side/weather_forecast_service
A weather forecast API and web dashboard built with NestJS. Pulls real-time data from OpenWeatherMap, caches results in SQLite, and serves both JSON API endpoints and a clean web interface. Deployed on Railway for easy access.
https://github.com/dax-side/weather_forecast_service
nestjs nestjs-api openweathermap railway rest-api sqlite typescript weather-api weather-forecast
Last synced: 25 days ago
JSON representation
A weather forecast API and web dashboard built with NestJS. Pulls real-time data from OpenWeatherMap, caches results in SQLite, and serves both JSON API endpoints and a clean web interface. Deployed on Railway for easy access.
- Host: GitHub
- URL: https://github.com/dax-side/weather_forecast_service
- Owner: dax-side
- Created: 2025-09-23T21:59:29.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-09-25T00:37:46.000Z (8 months ago)
- Last Synced: 2025-10-08T04:59:14.309Z (8 months ago)
- Topics: nestjs, nestjs-api, openweathermap, railway, rest-api, sqlite, typescript, weather-api, weather-forecast
- Language: TypeScript
- Homepage: https://weatherforecastservice-production.up.railway.app/
- Size: 132 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Weather Forecast Service
A comprehensive NestJS-based weather forecast API that provides current weather data and forecasts for cities worldwide using the OpenWeatherMap API.
## Features
- Real-time current weather data
- 5-day weather forecasts with 3-hour intervals
- City search tracking and statistics
- Scheduled background data refresh
- SQLite database with TypeORM
- Comprehensive API documentation with Swagger
- Input validation and error handling
- CORS enabled for cross-origin requests
## Tech Stack
- **Framework**: NestJS with TypeScript
- **Database**: SQLite with TypeORM
- **External API**: OpenWeatherMap API
- **Documentation**: Swagger/OpenAPI
- **Validation**: class-validator
- **Scheduling**: @nestjs/schedule
- **HTTP Client**: Axios
## Prerequisites
- Node.js (v16 or higher)
- npm or yarn
- OpenWeatherMap API key
## Installation
1. Clone the repository
```bash
git clone
cd weather_forecast_service
```
2. Install dependencies
```bash
npm install
```
3. Set up environment variables
Create a `.env` file in the root directory:
```
OPENWEATHER_API_KEY=your_openweathermap_api_key_here
PORT=3000
```
4. Build the application
```bash
npm run build
```
5. Start the application
```bash
npm start
```
The server will start on `http://localhost:3000`
## API Endpoints
### Weather Endpoints
- `GET /api/weather/current?city={cityName}` - Get current weather for a city
- `GET /api/weather/forecast?city={cityName}` - Get 5-day weather forecast
- `GET /api/weather/history` - Get search history
- `GET /api/weather/cities` - Get all tracked cities
### Dashboard Endpoints
- `GET /` - Main dashboard page
- `POST /search` - Search functionality
## API Documentation
Interactive API documentation is available at:
```
http://localhost:3000/api/docs
```
## Database Schema
The application uses four main entities:
### CityEntity
- Stores city information with coordinates
- Tracks search statistics
- Primary reference for weather data
### WeatherEntity
- Current weather data for cities
- Linked to CityEntity via foreign key
- Automatically updated on API calls
### ForecastEntity
- Weather forecast data points
- 3-hour interval forecasts up to 5 days
- Linked to CityEntity
### SearchHistoryEntity
- Tracks search patterns
- Records search frequency and timestamps
## Caching Strategy
- **Current Weather**: Cached for 15 minutes
- **Forecast Data**: Cached for 1 hour
- **Background Refresh**: Scheduled hourly updates for popular cities
## Error Handling
The API provides comprehensive error responses:
- `200 OK` - Success
- `400 Bad Request` - Invalid input or API key issues
- `404 Not Found` - City not found
- `500 Internal Server Error` - Server errors
## Development
### Available Scripts
- `npm start` - Start production server
- `npm run start:dev` - Start development server with hot reload
- `npm run build` - Build the application
- `npm run test` - Run tests
- `npm run lint` - Run ESLint
### Project Structure
```
src/
├── controllers/ # API controllers
├── services/ # Business logic services
├── entities/ # Database entities
├── dto/ # Data transfer objects
├── app.module.ts # Main application module
└── main.ts # Application entry point
```
## Configuration
### Environment Variables
- `OPENWEATHER_API_KEY` - Required: Your OpenWeatherMap API key
- `PORT` - Optional: Server port (default: 3000)
### Database
The application uses SQLite by default. The database file is automatically created as `weather.db` in the project root.
## Performance Considerations
- Database queries are optimized to prevent N+1 query problems
- API responses are cached to reduce external API calls
- Background tasks refresh popular city data proactively
- Proper indexing on frequently queried fields
## Security
- Input validation on all endpoints
- Environment variable protection for API keys
- CORS configuration for secure cross-origin access
- Error messages sanitized to prevent information leakage
## Monitoring and Logging
- Morgan middleware for HTTP request logging
- Structured logging for debugging and monitoring
- Error tracking with detailed stack traces in development