Weather Proxy API is a secure and production-ready backend service that fetches weather data from OpenWeather while keeping your API key hidden from client-side applications. It includes in-memory caching, request rate limiting, strict input validation, and Swagger-powered API documentation for fast development and safer integrations.
- Secure Proxy Architecture: Hides the
OPENWEATHER_API_KEYon the server and prevents direct key exposure in frontend apps. - Response Filtering: Returns only relevant weather fields so client payloads stay clean and predictable.
- In-Memory Caching: Serves repeated requests from memory with TTL support to reduce external API calls and latency.
- Rate Limiting Protection: Applies request limits on
/api/*routes to reduce abuse and improve service stability. - Input Validation: Validates
city,lat, andlonquery parameters before calling external APIs. - Interactive Swagger Docs: Auto-generates and serves API docs at
/api-docsfor easier testing and onboarding. - Security Middleware Stack: Uses Helmet, CORS, and a centralized error handler for safer defaults.
Also try:
- API docs: Swagger UI
- Health endpoint: Service status
- Node.js: JavaScript runtime for backend services.
- Express.js: Web framework for routing and middleware orchestration.
- Axios: HTTP client to communicate with OpenWeather endpoints.
- dotenv: Environment variable management for secure configuration.
- helmet: Secure HTTP headers for better baseline protection.
- cors: Controlled cross-origin access for frontend integrations.
- express-rate-limit: Request throttling middleware for abuse prevention.
- swagger-jsdoc: OpenAPI document generation from JSDoc comments.
- swagger-ui-express: Interactive Swagger UI hosting inside Express.
- nodemon: Development-time auto-reload for rapid iteration.
- Clone the repository.
- Install dependencies.
- Create and configure your
.envfile. - Start the development server.
git clone https://github.com/Serkanbyx/weather-proxy-api.git
cd weather-proxy-api
npm installCreate a .env file in the project root:
PORT=3000
OPENWEATHER_API_KEY=your_openweather_api_key
CACHE_TTL=600
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100Run the project:
# Development
npm run dev
# Production
npm startcode .Then use the integrated terminal:
npm install
npm run dev- Start the API locally with
npm run devor use the live Render deployment. - Open
/api-docsto inspect and test all endpoints interactively. - Call weather endpoints with either city or coordinate parameters.
- Monitor cache behavior through
/api/cache/stats. - Clear cache manually when needed with
DELETE /api/cache/flush.
Example request:
curl "http://localhost:3000/api/weather/current?city=Istanbul"- The client sends a request to
/api/weather/*. - Rate limiter checks quota for the current window.
- Query validation middleware validates required inputs.
- Service layer checks cache and returns cached data if available.
- If cache miss, API calls OpenWeather and filters the response.
- Filtered response is cached and returned to the client.
const cacheTtlSeconds = Number(process.env.CACHE_TTL || 600);
const rateLimitWindowMs = Number(process.env.RATE_LIMIT_WINDOW_MS || 900000);
const rateLimitMaxRequests = Number(process.env.RATE_LIMIT_MAX || 100);GET /api/weather/current?city={city}
GET /api/weather/current/coords?lat={lat}&lon={lon}
GET /api/weather/forecast?city={city}
GET /api/weather/forecast/coords?lat={lat}&lon={lon}
GET /api/cache/stats
DELETE /api/cache/flush
GET /
You can replace or extend OpenWeather integration inside src/services/weatherService.js by keeping response shapes stable for controllers.
async function fetchCurrentWeatherByCity(cityName) {
// Replace provider endpoint or add fallback providers here.
// Keep returned object format consistent with controller expectations.
}Adjust values in .env:
CACHE_TTL=300
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=30Add stricter constraints in src/middlewares/validateQuery.js to enforce custom city formats, regional whitelists, or coordinate precision.
- ✅ Secure API key handling with backend proxy design
- ✅ Current and forecast weather by city
- ✅ Current and forecast weather by coordinates
- ✅ In-memory caching with cache stats and flush operations
- ✅ Rate limiting on API routes
- ✅ Swagger documentation with OpenAPI schema generation
- ✅ Centralized error handling and middleware-based architecture
- Redis-based distributed cache for multi-instance deployments
- Request logging and tracing with correlation IDs
- API key authentication for consumer applications
- Unit and integration test suites with CI quality gates
- Multi-provider weather fallback strategy
- Fork the repository.
- Create a feature branch:
git checkout -b feat/amazing-improvement- Commit your changes using clear commit prefixes:
git commit -m "feat: add weather alerts endpoint"
git commit -m "fix: validate negative longitude values"
git commit -m "docs: update usage examples"- Push your branch:
git push origin feat/amazing-improvement- Open a Pull Request and describe:
- what changed,
- why it changed,
- how to test it.
This project is licensed under the MIT License. See the LICENSE file for details.
Serkanby
- Website: serkanbayraktar.com
- GitHub: @Serkanbyx
- Email: serkanbyx1@gmail.com
- OpenWeather API for weather data services.
- Render for deployment and hosting workflow.
- Express and Swagger community packages powering API infrastructure and documentation.
- Open an Issue
- Email: serkanbyx1@gmail.com
- Website: serkanbayraktar.com
⭐ If you like this project, don't forget to give it a star!