{"id":22433173,"url":"https://github.com/andresweitzel/microservice_openweather_nodejs_jest_aws","last_synced_at":"2026-05-05T04:32:44.544Z","repository":{"id":205012853,"uuid":"713191152","full_name":"andresWeitzel/Microservice_OpenWeather_Nodejs_Jest_AWS","owner":"andresWeitzel","description":"Microservice for the integration of the Open Weather API with focus on unit and integration tests implementing Nodejs, Jest, Serverless-framework, aws-lambda, api gateway, git, others.","archived":false,"fork":false,"pushed_at":"2024-01-26T21:32:30.000Z","size":1133,"stargazers_count":0,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T12:46:16.606Z","etag":null,"topics":["api-gateway","aws-lambda","git","integration-testing","jest","jest-tests","nodejs","serverless-framework","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andresWeitzel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-02T02:37:49.000Z","updated_at":"2024-01-11T19:57:45.000Z","dependencies_parsed_at":"2025-02-01T12:55:21.225Z","dependency_job_id":null,"html_url":"https://github.com/andresWeitzel/Microservice_OpenWeather_Nodejs_Jest_AWS","commit_stats":null,"previous_names":["andresweitzel/microservice_openweather_nodejs_jest_aws"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresWeitzel%2FMicroservice_OpenWeather_Nodejs_Jest_AWS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresWeitzel%2FMicroservice_OpenWeather_Nodejs_Jest_AWS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresWeitzel%2FMicroservice_OpenWeather_Nodejs_Jest_AWS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresWeitzel%2FMicroservice_OpenWeather_Nodejs_Jest_AWS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andresWeitzel","download_url":"https://codeload.github.com/andresWeitzel/Microservice_OpenWeather_Nodejs_Jest_AWS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245806328,"owners_count":20675296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","aws-lambda","git","integration-testing","jest","jest-tests","nodejs","serverless-framework","unit-testing"],"created_at":"2024-12-05T22:14:10.094Z","updated_at":"2026-05-05T04:32:44.526Z","avatar_url":"https://github.com/andresWeitzel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Index app](./doc/assets/img/open-weather.jpg)\n\n\u003cdiv align=\"right\"\u003e\n  \u003cimg width=\"25\" height=\"25\" src=\"./doc/assets/icons/devops/png/aws.png\" /\u003e\n  \u003cimg width=\"25\" height=\"25\" src=\"./doc/assets/icons/aws/png/lambda.png\" /\u003e\n  \u003cimg width=\"27\" height=\"27\" src=\"./doc/assets/icons/devops/png/postman.png\" /\u003e\n  \u003cimg width=\"29\" height=\"27\" src=\"./doc/assets/icons/devops/png/git.png\" /\u003e\n  \u003cimg width=\"28\" height=\"27\" src=\"./doc/assets/icons/aws/png/api-gateway.png\" /\u003e\n  \u003cimg width=\"27\" height=\"25\" src=\"./doc/assets/icons/aws/png/parameter-store.png\" /\u003e\n  \u003cimg width=\"27\" height=\"27\" src=\"./doc/assets/icons/backend/javascript-typescript/png/nodejs.png\" /\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003cbr\u003e\n\n\u003cdiv align=\"right\"\u003e\n    \u003ca href=\"./README.md\" target=\"_blank\"\u003e\n      \u003cimg src=\"./doc/assets/translation/arg-flag.jpg\" width=\"10%\" height=\"10%\" /\u003e\n  \u003c/a\u003e \n   \u003ca href=\"./README.md\" target=\"_blank\"\u003e\n      \u003cimg src=\"./doc/assets/translation/eeuu-flag.jpg\" width=\"10%\" height=\"10%\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# Microservice OpenWeather AWS ![(status-completed)](./doc/assets/icons/badges/status-completed.svg)\n\n\u003c/div\u003e  \n\nMicroservice for the integration of the Open Weather API with focus on unit and integration tests implementing Nodejs, Jest, Serverless-framework, aws-lambda, api gateway, git, others.  AWS services are tested locally. The project code and its documentation (less technical doc) have been developed in English.\n\n*   [Open Weather Guide](https://openweathermap.org/guide)\n*   [Open Weather Api keys](https://home.openweathermap.org/api_keys)\n*   [Playlist functionality test](https://www.youtube.com/watch?v=oLSrmqMq0Zs\\\u0026list=PLCl11UFjHurB9JzGtm5e8-yp52IcZDs5y) \u003ca href=\"https://www.youtube.com/watch?v=oLSrmqMq0Zs\\\u0026list=PLCl11UFjHurB9JzGtm5e8-yp52IcZDs5y\" target=\"_blank\"\u003e \u003cimg src=\"./doc/assets/social-networks/yt.png\" width=\"5%\" height=\"5%\" /\u003e \u003c/a\u003e\n\n\u003cbr\u003e\n\n## Index 📜\n\n\u003cdetails\u003e\n \u003csummary\u003e View details \u003c/summary\u003e\n\n\u003cdiv align=\"right\"\u003e\n\n`Latest update: 19/02/26` \n\n\u003c/div\u003e\n\n### Section 1) Description, configuration and technologies.\n\n*   [1.0) Project description.](#10-description-)\n*   [1.1) Project execution.](#12-project-execution-)\n    *   [1.1.1) OpenWeather API Configuration](#111-openweather-api-configuration)\n*   [1.1.2) Project Configuration File Setup](#112-project-configuration-file-setup)\n*   [1.1.3) API Key Security Best Practices](#113-api-key-security-best-practices)\n*   [1.1.4) OpenWeather API Endpoints Used](#114-openweather-api-endpoints-used)\n*   [1.1.5) Rate Limits and Pricing](#115-rate-limits-and-pricing)\n*   [1.1.6) Troubleshooting](#116-troubleshooting)\n*   [1.1.7) Additional Resources](#117-additional-resources)\n*   [1.1.8) Support](#118-support)\n*   [1.2) Technologies.](#12-technologies-)\n\n### Section 2) Endpoints and Examples\n\n*   [2.1) Weather Endpoints.](#21-weather-endpoints-)\n*   [2.2) Endpoints and resources.](#22-endpoints-and-resources-)\n*   [2.3) Examples.](#23-examples-)\n*   [2.4) Forecast Endpoints.](#24-forecast-endpoints-)\n*   [2.5) Forecast Examples.](#25-forecast-examples-)\n\n### Section 3) Data Persistence and Storage\n\n*   [3.1) Storage Architecture \u0026 Structure.](#31-storage-architecture--structure-)\n*   [3.2) Advanced Features \u0026 Performance.](#32-advanced-features--performance-)\n*   [3.3) Best Practices \u0026 Future Roadmap.](#33-best-practices--future-roadmap-)\n\n### Section 4) Functionality test and references\n\n*   [4.1) Functionality test.](#41-functionality-test-and-references-)\n*   [4.2) References.](#42-references-)\n\n\u003cbr\u003e\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Section 1) Description, configuration and technologies.\n\n### 1.0) Description [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n \u003cbr\u003e\n\n### 1.0.0) General description\n\nThis microservice provides a comprehensive **REST API for weather information** using the **OpenWeatherMap API**. It's built with **Node.js**, **Jest** for testing, **Serverless Framework**, and **AWS Lambda** for serverless deployment.\n\n#### 🌟 Key Features\n\n*   **🌤️ Complete Weather Data**: Current weather conditions for any location worldwide\n*   **📊 Advanced Forecasts**: 5-day weather forecasts with multiple filtering options\n*   **🔍 Multiple Search Methods**: Search by city name, coordinates, city ID, or postal code\n*   **🌍 Internationalization**: Support for multiple languages and units\n*   **⚡ Enhanced Endpoints**: Rich data with recommendations, alerts, and analysis\n*   **🛡️ Robust Architecture**: Circuit breaker, rate limiting, and caching\n*   **📝 Comprehensive Testing**: Unit and integration tests with Jest\n*   **☁️ AWS Ready**: Serverless deployment with Lambda and API Gateway\n\n#### 🎯 Target Use Cases\n\n*   **Weather Applications**: Mobile and web weather apps\n*   **IoT Projects**: Smart home and environmental monitoring\n*   **Travel Planning**: Tourism and travel applications\n*   **Business Intelligence**: Weather-dependent business decisions\n*   **Educational Projects**: Learning serverless architecture and API integration\n\n#### 🏗️ Architecture Overview\n\nThe microservice follows a **microservices architecture** pattern with:\n- **Serverless Functions**: AWS Lambda for scalable, cost-effective execution\n- **API Gateway**: RESTful API management and routing\n- **Parameter Store**: Secure environment variable management\n- **Caching Layer**: In-memory and file-based caching for performance\n- **Circuit Breaker**: Fault tolerance and resilience patterns\n\n### 1.0.1) Description Architecture and Operation\n\n#### 🏛️ System Architecture\n\nThe microservice implements a **layered architecture** with clear separation of concerns:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    API Gateway Layer                        │\n├─────────────────────────────────────────────────────────────┤\n│                  Controller Layer                           │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │   Weather   │ │  Forecast   │ │    Info     │           │\n│  │ Controllers │ │ Controllers │ │ Controllers │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n├─────────────────────────────────────────────────────────────┤\n│                   Middleware Layer                          │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │   Circuit   │ │    Rate     │ │   Metrics   │           │\n│  │   Breaker   │ │   Limiter   │ │  Collector  │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n├─────────────────────────────────────────────────────────────┤\n│                   Service Layer                             │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │   Cache     │ │  Transform  │ │   Validate  │           │\n│  │   Service   │ │   Service   │ │   Service   │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n├─────────────────────────────────────────────────────────────┤\n│                   External APIs                             │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │ OpenWeather │ │   AWS SSM   │ │   File      │           │\n│  │     API     │ │ Parameters  │ │   System    │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n#### 🔄 Request Flow\n\n1. **API Gateway**: Receives HTTP requests and routes to appropriate Lambda function\n2. **Controller Layer**: Validates parameters and orchestrates business logic\n3. **Middleware**: Applies cross-cutting concerns (rate limiting, circuit breaker, metrics)\n4. **Service Layer**: Processes data, applies transformations, and manages caching\n5. **External APIs**: Fetches data from OpenWeatherMap API\n6. **Response**: Returns formatted data with appropriate HTTP status codes\n\n#### 🛡️ Resilience Patterns\n\n*   **Circuit Breaker**: Prevents cascade failures when external APIs are down\n*   **Rate Limiting**: Protects against abuse and respects API quotas\n*   **Caching**: Reduces API calls and improves response times\n*   **Retry Logic**: Handles temporary failures gracefully\n*   **Fallback Responses**: Provides cached data when external services fail\n\n#### 📊 Data Flow\n\n1. **Input Validation**: Parameters are validated against schemas\n2. **Cache Check**: System checks for cached data first\n3. **API Call**: If not cached, calls OpenWeatherMap API\n4. **Data Transformation**: Applies business logic and enhancements\n5. **Storage**: Saves data to cache and JSON files\n6. **Response**: Returns formatted data to client\n\n#### 🔧 Technical Components\n\n*   **AWS Lambda**: Serverless compute for handling requests\n*   **API Gateway**: HTTP API management and routing\n*   **Parameter Store**: Secure configuration management\n*   **Jest**: Comprehensive testing framework\n*   **Serverless Framework**: Infrastructure as Code\n*   **Node.js**: Runtime environment for JavaScript execution\n\n\u003c/details\u003e\n\n\n### 1.1) Project execution [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n \u003cbr\u003e\n\n#### 1.1.1) OpenWeather API Configuration\n\nThis microservice integrates with the OpenWeather API to retrieve weather information. Follow these detailed steps to configure your API access:\n\n##### Step 1: Account Creation\n\n1.  **Visit OpenWeatherMap**: Go to \u003chttps://openweathermap.org/\u003e\n2.  **Sign Up**: Click \"Sign In\" → \"Sign Up\" in the top right corner\n3.  **Complete Registration**:\n    *   Enter your email address\n    *   Create a strong password\n    *   Accept terms and conditions\n    *   Click \"Create Account\"\n4.  **Email Verification**: Check your inbox and click the verification link\n\n##### Step 2: API Key Generation\n\n1.  **Login**: Sign in to your OpenWeather account\n2.  **Navigate to API Keys**: Go to \u003chttps://home.openweathermap.org/api_keys\u003e\n3.  **Default Key**: You'll see a default API key automatically generated\n4.  **⚠️ CRITICAL - Activation Time**: New API keys take **up to 2 hours to activate**\n5.  **Do NOT test immediately** - you'll get 401 \"Invalid API key\" errors until activation is complete\n\n##### Step 3: Configure the Project\n\n1.  **Open Configuration File**: Open the file `serverless-ssm.yml` in the project root\n2.  **Update API Key**: Replace the placeholder value with your actual API key:\n    ```yaml\n    # Environment variables for the OpenWeather API microservice\n    API_WEATHER_URL_BASE: \"https://api.openweathermap.org/data/2.5/weather?q=\"\n    API_FORECAST_URL_BASE: \"https://api.openweathermap.org/data/2.5/forecast?\"\n    API_KEY: \"YOUR_ACTUAL_API_KEY_HERE\"\n    ```\n\n##### Step 4: Test Your Configuration\n\n**⚠️ IMPORTANT: Wait for API Key Activation**\n\n**Before testing, ensure your API key has been active for at least 2 hours.** If you just created it, wait before proceeding.\n\n1.  **Start the Application**:\n    ```bash\n    npm start\n    ```\n\n2.  **Test the Endpoint**: Use your preferred HTTP client (Postman, curl, etc.):\n    ```bash\n    # Test with curl\n    curl http://localhost:4000/v1/weather/country/London\n    ```\n\n# Test with Postman\n\nGET http://localhost:4000/v1/weather/country/New%20York\n\n````\n\n3. **Expected Response**: A successful response should look like:\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"coord\": {\"lon\": -0.13, \"lat\": 51.51},\n    \"weather\": [{\"id\": 300, \"main\": \"Drizzle\", \"description\": \"light intensity drizzle\"}],\n    \"base\": \"stations\",\n    \"main\": {\n      \"temp\": 280.32,\n      \"pressure\": 1012,\n      \"humidity\": 81,\n      \"temp_min\": 279.15,\n      \"temp_max\": 281.15\n    },\n    \"visibility\": 10000,\n    \"wind\": {\"speed\": 4.1, \"deg\": 80},\n    \"clouds\": {\"all\": 90},\n    \"dt\": 1485789600,\n    \"sys\": {\n      \"type\": 1,\n      \"id\": 5091,\n      \"message\": 0.0103,\n      \"country\": \"GB\",\n      \"sunrise\": 1485762037,\n      \"sunset\": 1485794875\n    },\n    \"id\": 2643743,\n    \"name\": \"London\",\n    \"cod\": 200\n  }\n}\n````\n\n#### 1.1.2) Project Configuration File Setup\n\n**⚠️ CRITICAL: Create the Configuration File (if it does not exist)**\n\nBefore running the project, you **MUST** create the `serverless-ssm.yml` file in the project root directory. This file contains the environment variables needed for the microservice to function properly.\n\n##### Step 1: Create the Configuration File\n\n1.  **Navigate to Project Root**: Go to the main project directory\n2.  **Create New File**: Create a new file named `serverless-ssm.yml`\n3.  **Add Configuration**: Copy and paste the following content:\n\n```yaml\n# Environment variables for the OpenWeather API microservice\n    API_WEATHER_URL_BASE: \"https://api.openweathermap.org/data/2.5/weather?q=\"\n    API_FORECAST_URL_BASE: \"https://api.openweathermap.org/data/2.5/forecast?\"\n    API_KEY: \"YOUR_ACTUAL_API_KEY_HERE\"\n```\n\n##### Step 2: Update with Your API Key\n\nReplace `\"YOUR_ACTUAL_API_KEY_HERE\"` with the API key you obtained from OpenWeather:\n\n```yaml\n# Environment variables for the OpenWeather API microservice\n    API_WEATHER_URL_BASE: \"https://api.openweathermap.org/data/2.5/weather?q=\"\n    API_FORECAST_URL_BASE: \"https://api.openweathermap.org/data/2.5/forecast?\"\n    API_KEY: \"858923c0cff4df1c4415f2493500ad37\"  # Replace with your actual API key\n```\n\n##### Step 3: Verify File Location\n\nEnsure the file is in the correct location:\n\n    Microservice_OpenWeather_Nodejs_Jest_AWS/\n    ├── serverless-ssm.yml          # ← This file must exist here\n    ├── package.json\n    ├── serverless.yml\n    ├── src/\n    └── ...\n\n##### Step 4: Security Considerations\n\n*   ✅ **Add to .gitignore** - Ensure `serverless-ssm.yml` is in your `.gitignore` file\n*   ✅ **Keep private** - Never commit this file to version control\n*   ✅ **Backup safely** - Store your API key in a secure location\n*   ❌ **Don't share** - Never share your API key publicly\n*   ❌ **Don't commit** - Avoid accidentally committing to git\n\n**Example .gitignore entry:**\n\n    # Configuration files with sensitive data\n    serverless-ssm.yml\n    *.env\n\n#### 1.1.3) API Key Security Best Practices\n\n*   ✅ **Wait for activation** - New keys take up to 2 hours to activate\n*   ✅ **Keep your API key private** - Never share it publicly\n*   ✅ **Use environment variables** - Don't hardcode in source code\n*   ✅ **Monitor usage** - Stay within free tier limits (1,000 calls/day)\n*   ✅ **Rotate keys** - Create new keys if compromised\n*   ❌ **Don't test immediately** - You'll get 401 errors until activation\n*   ❌ **Don't commit to git** - Add config files to .gitignore\n*   ❌ **Don't share in logs** - Avoid logging API keys\n\n#### 1.1.4) OpenWeather API Endpoints Used\n\nThis microservice uses the **Current Weather Data** endpoint:\n\n*   **Base URL**: `https://api.openweathermap.org/data/2.5/weather`\n*   **Method**: GET\n*   **Parameters**:\n    *   `q`: City name (e.g., \"London\", \"New York\")\n    *   `appid`: Your API key\n*   **Response**: JSON with weather data including temperature, humidity, wind, etc.\n\n#### 1.1.5) Rate Limits and Pricing\n\n| Plan | Calls/Day | Features |\n|------|-----------|----------|\n| Free | 1,000 | Current weather, 5-day forecast |\n| Starter | 100,000 | Extended forecast, historical data |\n| Business | 1,000,000 | All features, priority support |\n\n*   **Response Time**: Usually under 200ms\n*   **Data Update**: Every 10 minutes\n\n#### 1.1.6) Troubleshooting\n\n##### ⚠️ IMPORTANT: API Key Activation Time\n\n**New API keys require up to 2 hours to activate.** This is the most common cause of 401 errors.\n\n**What happens:**\n\n*   You create a new API key\n*   You test it immediately with curl or your application\n*   You get 401 \"Invalid API key\" error\n*   You think something is wrong with your setup\n\n**Solution:**\n\n*   **Wait 2 hours** after creating the key\n*   Don't panic - this is normal behavior\n*   Set a reminder and test again later\n\n##### Common Issues\n\n**1. \"401 Unauthorized\" Error**\n\n*   **Cause**: Invalid or inactive API key\n*   **Solution**:\n    *   **⚠️ Most Common**: Wait up to 2 hours for new keys to activate\n    *   Verify your API key is correct (no extra spaces)\n    *   Check if you've exceeded daily limits\n    *   If testing immediately after creation, this is normal - wait 2 hours\n\n**2. \"404 Not Found\" Error**\n\n*   **Cause**: Invalid city name or country\n*   **Solution**:\n    *   Use correct city names (e.g., \"London\" not \"Londres\")\n    *   Check spelling and formatting\n    *   Try with country code: \"London,UK\"\n\n**3. \"429 Too Many Requests\" Error**\n\n*   **Cause**: Exceeded rate limits\n*   **Solution**:\n    *   Wait before making more requests\n    *   Check your daily usage\n    *   Consider upgrading to paid plan\n\n**4. Environment Variables Not Loading**\n\n*   **Cause**: Configuration file issues\n*   **Solution**:\n    *   Verify `serverless-ssm.yml` exists\n    *   Check file format (YAML syntax)\n    *   Restart the application\n\n##### Debug Steps\n\n1.  **Check API Key**: Verify it's active in OpenWeather dashboard\n2.  **Test Direct API Call**: Use curl to test OpenWeather directly\n3.  **Check Logs**: Look for error messages in application logs\n4.  **Verify Configuration**: Ensure all environment variables are set\n\n##### Direct API Test\n\nTest your API key directly with OpenWeather:\n\n```bash\ncurl \"https://api.openweathermap.org/data/2.5/weather?q=London\u0026appid=YOUR_API_KEY\"\n```\n\n#### 1.1.7) Additional Resources\n\n*   [OpenWeather API Documentation](https://openweathermap.org/api)\n*   [API Key Management](https://home.openweathermap.org/api_keys)\n*   [Weather Conditions Codes](https://openweathermap.org/weather-conditions)\n*   [Support Forum](https://openweathermap.org/forum)\n\n#### 1.1.8) Support\n\nIf you continue to have issues:\n\n1.  Check the [OpenWeather FAQ](https://openweathermap.org/faq)\n2.  Visit the [OpenWeather Forum](https://openweathermap.org/forum)\n3.  Contact OpenWeather support for API-specific issues\n4.  Check this project's issues for known problems\n\n\u003cbr\u003e\n\n\u003c/details\u003e\n\n### 1.2) Technologies [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n \u003cbr\u003e\n\n#### 🏗️ Core Technologies\n\n| **Technology** | **Version** | **Purpose** | **Role in Project** |\n| ------------- | ------------- | ------------- | ------------- |\n| [Node.js](https://nodejs.org/) | 14.18.1 | JavaScript Runtime | Core runtime environment for serverless functions |\n| [Serverless Framework](https://www.serverless.com/) | 3.23.0 | Infrastructure as Code | AWS deployment and configuration management |\n| [AWS Lambda](https://aws.amazon.com/lambda/) | Latest | Serverless Compute | Function execution platform |\n| [AWS API Gateway](https://aws.amazon.com/api-gateway/) | 2.0 | API Management | HTTP API routing and management |\n| [AWS Systems Manager](https://aws.amazon.com/systems-manager/) | 3.0 | Parameter Store | Secure environment variable management |\n\n#### 🧪 Testing \u0026 Quality\n\n| **Technology** | **Version** | **Purpose** | **Role in Project** |\n| ------------- | ------------- | ------------- | ------------- |\n| [Jest](https://jestjs.io/) | 29.7.0 | Testing Framework | Unit and integration testing |\n| [Supertest](https://github.com/visionmedia/supertest) | Latest | HTTP Testing | API endpoint testing |\n| [ESLint](https://eslint.org/) | Latest | Code Linting | Code quality and style enforcement |\n| [Prettier](https://prettier.io/) | Latest | Code Formatting | Consistent code formatting |\n\n#### 🔌 Serverless Plugins\n\n| **Plugin** | **Version** | **Purpose** | **Configuration** |\n| ------------- | ------------- | ------------- | ------------- |\n| [serverless-offline](https://www.npmjs.com/package/serverless-offline) | Latest | Local Development | Local Lambda simulation |\n| [serverless-offline-ssm](https://www.npmjs.com/package/serverless-offline-ssm) | Latest | Parameter Store Simulation | Local SSM parameter simulation |\n| [serverless-auto-swagger](https://www.npmjs.com/package/serverless-auto-swagger) | Latest | API Documentation | Automatic OpenAPI documentation |\n\n#### 🛠️ Development Tools\n\n| **Tool** | **Version** | **Purpose** | **Usage** |\n| ------------- | ------------- | ------------- | ------------- |\n| [Visual Studio Code](https://code.visualstudio.com/) | 1.72.2+ | IDE | Primary development environment |\n| [Postman](https://www.postman.com/) | 10.11+ | API Testing | Endpoint testing and documentation |\n| [Git](https://git-scm.com/) | 2.29.1+ | Version Control | Source code management |\n| [npm](https://www.npmjs.com/) | 6.14+ | Package Manager | Dependency management |\n\n#### 📦 Key Dependencies\n\n| **Package** | **Version** | **Purpose** | **Usage** |\n| ------------- | ------------- | ------------- | ------------- |\n| [axios](https://axios-http.com/) | Latest | HTTP Client | OpenWeather API requests |\n| [lodash](https://lodash.com/) | Latest | Utility Library | Data manipulation and utilities |\n| [moment](https://momentjs.com/) | Latest | Date/Time Library | Date formatting and manipulation |\n| [joi](https://joi.dev/) | Latest | Validation Library | Input parameter validation |\n\n#### 🏗️ Architecture Components\n\n| **Component** | **Technology** | **Purpose** | **Implementation** |\n| ------------- | ------------- | ------------- | ------------- |\n| **API Gateway** | AWS API Gateway | HTTP API Management | RESTful endpoint routing |\n| **Lambda Functions** | AWS Lambda | Serverless Compute | Individual endpoint handlers |\n| **Parameter Store** | AWS SSM | Configuration Management | Secure API keys and settings |\n| **Caching** | In-Memory + File | Performance Optimization | Response caching and storage |\n| **Circuit Breaker** | Custom Implementation | Fault Tolerance | External API failure protection |\n| **Rate Limiting** | Custom Implementation | API Protection | Request throttling and abuse prevention |\n\n#### 🌐 External APIs\n\n| **Service** | **Purpose** | **Integration** | **Data Format** |\n| ------------- | ------------- | ------------- | ------------- |\n| [OpenWeatherMap API](https://openweathermap.org/api) | Weather Data Source | REST API Integration | JSON |\n| [OpenWeatherMap Forecast API](https://openweathermap.org/forecast5) | Weather Forecast Data | REST API Integration | JSON |\n\n#### 🔧 Development Extensions (VSCode)\n\n| **Extension** | **Purpose** | **Benefits** |\n| ------------- | ------------- | ------------- |\n| **Prettier** | Code Formatting | Consistent code style |\n| **ESLint** | Code Linting | Code quality enforcement |\n| **YAML** | YAML Support | Serverless configuration files |\n| **Error Lens** | Error Highlighting | Inline error display |\n| **Tabnine** | AI Code Completion | Intelligent code suggestions |\n| **Thunder Client** | API Testing | Built-in HTTP client |\n| **GitLens** | Git Integration | Enhanced Git functionality |\n\n#### 📊 Monitoring \u0026 Observability\n\n| **Component** | **Purpose** | **Implementation** |\n| ------------- | ------------- | ------------- |\n| **Metrics Collection** | Performance Monitoring | Custom metrics middleware |\n| **Logging** | Debug \u0026 Monitoring | Structured logging with timestamps |\n| **Health Checks** | Service Status | Dedicated health endpoint |\n| **Error Tracking** | Issue Detection | Comprehensive error handling |\n\n#### 🚀 Deployment \u0026 DevOps\n\n| **Tool/Service** | **Purpose** | **Configuration** |\n| ------------- | ------------- | ------------- |\n| **Serverless Framework** | Infrastructure Deployment | `serverless.yml` configuration |\n| **AWS CloudFormation** | Resource Provisioning | Automatic via Serverless Framework |\n| **GitHub Actions** | CI/CD Pipeline | Automated testing and deployment |\n| **AWS CloudWatch** | Monitoring \u0026 Logging | Centralized observability |\n\n\u003cbr\u003e\n\n#### 🔄 Technology Stack Flow\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Development Layer                        │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │   VSCode    │ │   Postman   │ │     Git     │           │\n│  │     IDE     │ │   Testing   │ │   Version   │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n├─────────────────────────────────────────────────────────────┤\n│                    Application Layer                        │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │   Node.js   │ │   Jest      │ │  Serverless │           │\n│  │   Runtime   │ │   Testing   │ │  Framework  │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n├─────────────────────────────────────────────────────────────┤\n│                    AWS Cloud Layer                          │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │    Lambda   │ │ API Gateway │ │     SSM     │           │\n│  │  Functions  │ │  Management │ │ Parameters  │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n├─────────────────────────────────────────────────────────────┤\n│                  External Services                          │\n│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │\n│  │ OpenWeather │ │   GitHub    │ │ CloudWatch  │           │\n│  │     API     │ │    Actions  │ │ Monitoring  │           │\n│  └─────────────┘ └─────────────┘ └─────────────┘           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Section 2) Endpoints and Examples.\n\n### 2.1) Weather Endpoints [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n\u003cbr\u003e\n\nThis section describes all weather endpoints implemented in the microservice, each corresponding to a different variant of the OpenWeatherMap API.\n\n\n***\n\n## 📊 Endpoint Comparison\n\n| Endpoint | Parameters | Use Case | Example |\n|----------|------------|----------|---------|\n| `/v1/weather/location/{location}` | City | Search by name | Buenos Aires |\n| `/v1/weather-enhanced/location/{location}` | City | Enriched data | Buenos Aires |\n| `/v1/weather/coordinates/{lat}/{lon}` | Coordinates | GPS applications | -34.6132, -58.3772 |\n| `/v1/weather-enhanced/coordinates/{lat}/{lon}` | Coordinates | Enriched GPS data | -34.6132, -58.3772 |\n| `/v1/weather/id/{cityId}` | ID | Fast search | 3435910 |\n| `/v1/weather-enhanced/id/{cityId}` | ID | Enriched ID data | 3435910 |\n| `/v1/weather/zipcode/{zipcode}/{countryCode}` | Postal + Country | Local search | 10001, us |\n| `/v1/weather-enhanced/zipcode/{zipcode}/{countryCode}` | Postal + Country | Enriched postal data | 10001, us |\n| `/v1/weather/units/{location}/{units}` | City + Units | User preferences | London, metric |\n| `/v1/weather/language/{location}/{language}` | City + Language | Internationalization | Paris, es |\n| `/v1/weather/combined/{location}/{units}/{language}` | All (optional) | Complete configuration | Tokyo, metric, es |\n| `/v1/weather-enhanced/combined/{location}/{units}/{language}` | All (required) | Complete enriched configuration | Tokyo, metric, es |\n\n\n\n## 1. By City Name\n\n**Original Endpoint** (renamed for consistency)\n\n    GET /v1/weather/location/{location}\n\n**Description**: Get weather data by city name\n**Parameters**:\n\n*   `location`: City name (e.g., \"Buenos Aires\", \"London\")\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather/location/Buenos%20Aires\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-location.js`\n\n### 1.1. Enhanced Weather by City Name\n\n**Enhanced Endpoint**\n\n    GET /v1/weather-enhanced/location/{location}\n\n**Description**: Get enriched weather data by city name\n**Parameters**:\n\n*   `location`: City name (e.g., \"Buenos Aires\", \"London\")\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather-enhanced/location/Buenos%20Aires\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-location-enhanced.js`\n\n**Additional Features**:\n\n*   Temperature conversions (Kelvin, Celsius, Fahrenheit)\n*   Personalized recommendations\n*   Smart alerts\n*   Comfort analysis\n*   Sun information\n\n***\n\n## 2. By Coordinates\n\n**New Endpoint**\n\n    GET /v1/weather/coordinates/{lat}/{lon}\n\n**Description**: Get weather data by geographical coordinates\n**Parameters**:\n\n*   `lat`: Latitude (-90 to 90)\n*   `lon`: Longitude (-180 to 180)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather/coordinates/-34.6132/-58.3772\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?lat={lat}\u0026lon={lon}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-coordinates.js`\n\n**Validations**:\n\n*   Latitude must be between -90 and 90\n*   Longitude must be between -180 and 180\n*   Both parameters must be valid numbers\n\n### 2.1. Enhanced Weather by Coordinates\n\n**Enhanced Endpoint**\n\n    GET /v1/weather-enhanced/coordinates/{lat}/{lon}\n\n**Description**: Get enriched weather data by geographical coordinates\n**Parameters**:\n\n*   `lat`: Latitude (-90 to 90)\n*   `lon`: Longitude (-180 to 180)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather-enhanced/coordinates/-34.6132/-58.3772\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?lat={lat}\u0026lon={lon}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-coordinates-enhanced.js`\n\n**Additional Features**:\n\n*   Temperature conversions (Kelvin, Celsius, Fahrenheit)\n*   Personalized recommendations\n*   Smart alerts\n*   Comfort analysis\n*   Sun information\n\n***\n\n## 3. By City ID\n\n**New Endpoint**\n\n    GET /v1/weather/id/{cityId}\n\n**Description**: Get weather data by unique city ID\n**Parameters**:\n\n*   `cityId`: Numerical city ID (e.g., 3435910 for Buenos Aires)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather/id/3435910\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?id={city_id}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-id.js`\n\n**Validations**:\n\n*   ID must be a positive number\n*   ID must be a valid integer\n\n### 3.1. Enhanced Weather by City ID\n\n**Enhanced Endpoint**\n\n    GET /v1/weather-enhanced/id/{cityId}\n\n**Description**: Get enriched weather data by unique city ID\n**Parameters**:\n\n*   `cityId`: Numerical city ID (e.g., 3435910 for Buenos Aires)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather-enhanced/id/3435910\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?id={city_id}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-id-enhanced.js`\n\n**Additional Features**:\n\n*   Temperature conversions (Kelvin, Celsius, Fahrenheit)\n*   Personalized recommendations\n*   Smart alerts\n*   Comfort analysis\n*   Sun information\n\n***\n\n## 4. By Postal Code\n\n**Endpoint**\n\n    GET /v1/weather/zipcode/{zipcode}/{countryCode}\n\n**Description**: Get weather data by postal code\n**Parameters**:\n\n*   `zipcode`: Postal code (e.g., \"10001\", \"SW1A 1AA\")\n*   `countryCode`: Country code (required, e.g., \"us\", \"gb\")\n\n**Example**:\n\n```bash\n# With country code\ncurl http://localhost:4000/v1/weather/zipcode/10001/us\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?zip={zip},{country}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-zipcode.js`\n\n**Validations**:\n\n*   Zipcode must have valid format (2-20 characters, letters, numbers, spaces, hyphens, dots and commas)\n*   Country code is required\n*   Zipcode must be alphanumeric with allowed special characters\n\n### 4.1. Enhanced Weather by Postal Code\n\n**Enhanced Endpoint**\n\n    GET /v1/weather-enhanced/zipcode/{zipcode}/{countryCode}\n\n**Description**: Get enriched weather data by postal code\n**Parameters**:\n\n*   `zipcode`: Postal code (e.g., \"10001\", \"SW1A 1AA\")\n*   `countryCode`: Country code (required, e.g., \"us\", \"gb\")\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/weather-enhanced/zipcode/10001/us\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?zip={zip},{country}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-zipcode-enhanced.js`\n\n**Additional Features**:\n\n*   Temperature conversions (Kelvin, Celsius, Fahrenheit)\n*   Personalized recommendations\n*   Smart alerts\n*   Comfort analysis\n*   Sun information\n\n***\n\n## 5. With Specific Units\n\n**New Endpoint**\n\n    GET /v1/weather/units/{location}/{units}\n\n**Description**: Get weather data with specific units\n**Parameters**:\n\n*   `location`: City name\n*   `units`: Unit type (`metric`, `imperial`, `kelvin`)\n\n**Examples**:\n\n```bash\n# Temperature in Celsius\ncurl http://localhost:4000/v1/weather/units/London/metric\n\n# Temperature in Fahrenheit\ncurl http://localhost:4000/v1/weather/units/New%20York/imperial\n\n# Temperature in Kelvin (default)\ncurl http://localhost:4000/v1/weather/units/Tokyo/kelvin\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?q={city}\u0026units={units}\u0026appid={API_KEY}`\n\n**Controller**: `get-with-units.js`\n\n**Available Units**:\n\n*   `metric`: Celsius, m/s, hPa\n*   `imperial`: Fahrenheit, mph, hPa\n*   `kelvin`: Kelvin, m/s, hPa (default)\n\n***\n\n## 6. With Specific Language\n\n**New Endpoint**\n\n    GET /v1/weather/language/{location}/{language}\n\n**Description**: Get weather data with descriptions in specific language\n**Parameters**:\n\n*   `location`: City name\n*   `language`: Language code\n\n**Examples**:\n\n```bash\n# Spanish\ncurl http://localhost:4000/v1/weather/language/Paris/es\n\n# French\ncurl http://localhost:4000/v1/weather/language/London/fr\n\n# German\ncurl http://localhost:4000/v1/weather/language/Berlin/de\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?q={city}\u0026lang={lang}\u0026appid={API_KEY}`\n\n**Controller**: `get-with-language.js`\n\n**Available Languages**:\n\n*   `en`: English (default)\n*   `es`: Spanish\n*   `fr`: French\n*   `de`: German\n*   `it`: Italian\n*   `pt`: Portuguese\n*   `ru`: Russian\n*   `ja`: Japanese\n*   `ko`: Korean\n*   `zh_cn`: Simplified Chinese\n*   `zh_tw`: Traditional Chinese\n*   `ar`: Arabic\n*   `hi`: Hindi\n*   `th`: Thai\n*   `tr`: Turkish\n*   `vi`: Vietnamese\n\n***\n\n## 7. With Combined Parameters\n\n**Endpoint**\n\n    GET /v1/weather/combined/{location}/{units}/{language}\n\n**Description**: Get weather data with multiple combined parameters\n**Parameters**:\n\n*   `location`: City name (required)\n*   `units`: Unit type (optional, default: kelvin)\n*   `language`: Language code (optional, default: en)\n\n**Example**:\n\n```bash\n# All parameters\ncurl http://localhost:4000/v1/weather/combined/Tokyo/metric/es\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?q={city}\u0026units={units}\u0026lang={lang}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-combined.js`\n\n### 7.1. Enhanced Weather with Combined Parameters\n\n**Enhanced Endpoint**\n\n    GET /v1/weather-enhanced/combined/{location}/{units}/{language}\n\n**Description**: Get enriched weather data with multiple combined parameters\n**Parameters**:\n\n*   `location`: City name (required)\n*   `units`: Unit type (required)\n*   `language`: Language code (required)\n\n**Example**:\n\n```bash\n# Enhanced with all parameters (all required)\ncurl http://localhost:4000/v1/weather-enhanced/combined/Tokyo/metric/es\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/weather?q={city}\u0026units={units}\u0026lang={lang}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-combined-enhanced.js`\n\n**Additional Features**:\n\n*   Temperature conversions (Kelvin, Celsius, Fahrenheit)\n*   Personalized recommendations\n*   Smart alerts\n*   Comfort analysis\n*   Sun information\n\n**Note**: In the enhanced endpoint, all parameters are required.\n\n***\n\n## 🔧 Common Features\n\nAll implemented endpoints include:\n\n### ✅ Parameter Validation\n\n*   Data type validation\n*   Allowed ranges for coordinates\n*   Valid language codes\n*   Valid units\n\n### ✅ Cache System\n\n*   10-minute cache\n*   Unique keys per endpoint type\n*   Reduced OpenWeatherMap calls\n\n### ✅ Data Storage\n\n*   Automatic JSON file saving\n*   Organized structure by endpoint type\n*   Persistence for later analysis\n\n### ✅ Error Handling\n\n*   Appropriate HTTP responses\n*   Descriptive error messages\n*   Detailed logging\n\n### ✅ Logging\n\n*   Generated URL logging\n*   Cache usage information\n*   Errors and warnings\n\n***\n\n## 🚀 Complete Usage Examples\n\n### Example 1: GPS Application\n\n```bash\n# Get weather by GPS coordinates\ncurl http://localhost:4000/v1/weather/coordinates/40.7128/-74.0060\n```\n\n### Example 2: Multilingual Application\n\n```bash\n# Weather in Spanish for Spanish-speaking users\ncurl http://localhost:4000/v1/weather/language/Madrid/es\n```\n\n### Example 3: Application with User Preferences\n\n```bash\n# Weather in Celsius for European user\ncurl http://localhost:4000/v1/weather/units/Paris/metric\n```\n\n### Example 4: Complete Configuration\n\n```bash\n# Complete weather with all preferences\ncurl http://localhost:4000/v1/weather/combined/Tokyo/metric/es\n```\n\n### Example 5: Enhanced Weather with Rich Data\n\n```bash\n# Enhanced weather with additional analysis\ncurl http://localhost:4000/v1/weather-enhanced/combined/Madrid/metric/es\n```\n\n***\n\n## 📝 Important Notes\n\n1.  **API Key**: All endpoints require a valid OpenWeatherMap API key\n2.  **Rate Limits**: Respect API limits (1000 calls/day on free plan)\n3.  **Activation**: New API keys take up to 2 hours to activate\n4.  **Cache**: Data is cached for 10 minutes to optimize performance\n5.  **Storage**: Data is automatically saved to JSON files\n\n***\n\n## 🔗 References\n\n*   [OpenWeatherMap API Documentation](https://openweathermap.org/api)\n*   [Weather API Endpoints](https://openweathermap.org/api/weather-data)\n*   [Supported Languages](https://openweathermap.org/current#multi)\n*   [Units Format](https://openweathermap.org/current#data)\n\n\u003c/details\u003e\n\n### 2.3) Weather Endpoint Examples [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\u003cbr\u003e\n\n#### Basic Weather Endpoint\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/weather/location/London\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"coord\": {\"lon\": -0.13, \"lat\": 51.51},\n    \"weather\": [{\"id\": 300, \"main\": \"Drizzle\", \"description\": \"light intensity drizzle\"}],\n    \"main\": {\n      \"temp\": 280.32,\n      \"pressure\": 1012,\n      \"humidity\": 81\n    },\n    \"name\": \"London\",\n    \"cod\": 200\n  }\n}\n```\n\n#### Enhanced Weather Endpoint\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/weather-enhanced/location/London\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"location\": {\n      \"city\": \"London\",\n      \"country\": \"GB\",\n      \"coordinates\": {\"lon\": -0.13, \"lat\": 51.51},\n      \"timezone\": 0,\n      \"localTime\": \"2024-01-15T14:30:00.000Z\",\n      \"isDaytime\": true\n    },\n    \"temperature\": {\n      \"kelvin\": 280.32,\n      \"celsius\": 7.17,\n      \"fahrenheit\": 44.91,\n      \"feels_like\": {\n        \"kelvin\": 278.15,\n        \"celsius\": 5.0,\n        \"fahrenheit\": 41.0\n      }\n    },\n    \"weather\": {\n      \"condition\": \"Drizzle\",\n      \"description\": \"light intensity drizzle\",\n      \"icon\": \"09d\",\n      \"severity\": \"light\",\n      \"recommendation\": \"Bring an umbrella or raincoat\"\n    },\n    \"atmosphere\": {\n      \"pressure\": 1012,\n      \"humidity\": 81,\n      \"visibility\": 10000,\n      \"clouds\": 90\n    },\n    \"wind\": {\n      \"speed\": 4.1,\n      \"direction\": 80,\n      \"description\": \"Gentle breeze\"\n    },\n    \"sun\": {\n      \"sunrise\": \"07:45 AM\",\n      \"sunset\": \"04:30 PM\",\n      \"dayLength\": \"8h 45m\"\n    },\n    \"alerts\": [\n      {\n        \"type\": \"temperature\",\n        \"level\": \"moderate\",\n        \"message\": \"Cold temperatures expected\"\n      }\n    ],\n    \"recommendations\": {\n      \"clothing\": \"Warm jacket or coat\",\n      \"activities\": \"Indoor activities preferred\",\n      \"transport\": \"Normal transport conditions\",\n      \"health\": \"Wear warm clothing\"\n    },\n    \"comfort\": {\n      \"index\": 6.5,\n      \"level\": \"cool\"\n    }\n  }\n}\n```\n\n#### Search City IDs Endpoint\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/info/city-ids/London/GB\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"searchQuery\": \"London\",\n    \"countryCode\": \"GB\",\n    \"limit\": 5,\n    \"totalResults\": 1,\n    \"source\": \"local_database\",\n    \"databaseInfo\": {\n      \"version\": \"1.0.0\",\n      \"totalCities\": 150,\n      \"lastUpdated\": \"2024-01-15\"\n    },\n    \"cities\": [\n      {\n        \"id\": 2643743,\n        \"name\": \"London\",\n        \"state\": \"England\",\n        \"country\": \"GB\",\n        \"coordinates\": {\n          \"lat\": 51.5074,\n          \"lon\": -0.1276\n        },\n        \"displayName\": \"London, England, GB\"\n      }\n    ]\n  }\n}\n```\n\n**Database Features:**\n\n*   **📊 150+ Cities**: Major cities from around the world\n*   **🌍 Multiple Countries**: Cities with same name in different countries\n*   **⚡ Fast Response**: No external API calls needed\n*   **🔍 Partial Matching**: Find cities with partial name searches\n*   **📅 Always Available**: Works offline, no dependency on external services\n\n#### Enhanced Weather by City ID Endpoint\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/weather-enhanced/id/2643743\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"location\": {\n      \"city\": \"London\",\n      \"country\": \"GB\",\n      \"coordinates\": {\"lon\": -0.1276, \"lat\": 51.5074},\n      \"timezone\": 0,\n      \"localTime\": \"2024-01-15T14:30:00.000Z\",\n      \"isDaytime\": true\n    },\n    \"temperature\": {\n      \"kelvin\": 280.32,\n      \"celsius\": 7.17,\n      \"fahrenheit\": 44.91,\n      \"feels_like\": {\n        \"kelvin\": 278.15,\n        \"celsius\": 5.0,\n        \"fahrenheit\": 41.0\n      }\n    },\n    \"weather\": {\n      \"condition\": \"Drizzle\",\n      \"description\": \"light intensity drizzle\",\n      \"icon\": \"09d\",\n      \"severity\": \"light\",\n      \"recommendation\": \"Bring an umbrella or raincoat\"\n    },\n    \"atmosphere\": {\n      \"pressure\": 1012,\n      \"humidity\": 81,\n      \"visibility\": 10000,\n      \"clouds\": 90\n    },\n    \"wind\": {\n      \"speed\": 4.1,\n      \"direction\": 80,\n      \"description\": \"Gentle breeze\"\n    },\n    \"sun\": {\n      \"sunrise\": \"07:45 AM\",\n      \"sunset\": \"04:30 PM\",\n      \"dayLength\": \"8h 45m\"\n    },\n    \"alerts\": [\n      {\n        \"type\": \"temperature\",\n        \"level\": \"moderate\",\n        \"message\": \"Cold temperatures expected\"\n      }\n    ],\n    \"recommendations\": {\n      \"clothing\": \"Warm jacket or coat\",\n      \"activities\": \"Indoor activities preferred\",\n      \"transport\": \"Normal transport conditions\",\n      \"health\": \"Wear warm clothing\"\n    },\n    \"comfort\": {\n      \"index\": 6.5,\n      \"level\": \"cool\"\n    }\n  }\n}\n```\n\n#### Enhanced Weather by Coordinates Endpoint\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/weather-enhanced/coordinates/51.5074/-0.1276\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"location\": {\n      \"city\": \"London\",\n      \"country\": \"GB\",\n      \"coordinates\": {\"lon\": -0.1276, \"lat\": 51.5074},\n      \"timezone\": 0,\n      \"localTime\": \"2024-01-15T14:30:00.000Z\",\n      \"isDaytime\": true\n    },\n    \"temperature\": {\n      \"kelvin\": 280.32,\n      \"celsius\": 7.17,\n      \"fahrenheit\": 44.91,\n      \"feels_like\": {\n        \"kelvin\": 278.15,\n        \"celsius\": 5.0,\n        \"fahrenheit\": 41.0\n      }\n    },\n    \"weather\": {\n      \"condition\": \"Drizzle\",\n      \"description\": \"light intensity drizzle\",\n      \"icon\": \"09d\",\n      \"severity\": \"light\",\n      \"recommendation\": \"Bring an umbrella or raincoat\"\n    },\n    \"atmosphere\": {\n      \"pressure\": 1012,\n      \"humidity\": 81,\n      \"visibility\": 10000,\n      \"clouds\": 90\n    },\n    \"wind\": {\n      \"speed\": 4.1,\n      \"direction\": 80,\n      \"description\": \"Gentle breeze\"\n    },\n    \"sun\": {\n      \"sunrise\": \"07:45 AM\",\n      \"sunset\": \"04:30 PM\",\n      \"dayLength\": \"8h 45m\"\n    },\n    \"alerts\": [\n      {\n        \"type\": \"temperature\",\n        \"level\": \"moderate\",\n        \"message\": \"Cold temperatures expected\"\n      }\n    ],\n    \"recommendations\": {\n      \"clothing\": \"Warm jacket or coat\",\n      \"activities\": \"Indoor activities preferred\",\n      \"transport\": \"Normal transport conditions\",\n      \"health\": \"Wear warm clothing\"\n    },\n    \"comfort\": {\n      \"index\": 6.5,\n      \"level\": \"cool\"\n    }\n  }\n}\n```\n\n#### Testing with curl\n\n```bash\n# Test basic endpoint\ncurl http://localhost:4000/v1/weather/location/New%20York\n\n# Test enhanced endpoint\ncurl http://localhost:4000/v1/weather-enhanced/location/Paris\n\n# Test with different cities\ncurl http://localhost:4000/v1/weather-enhanced/location/Tokyo\ncurl http://localhost:4000/v1/weather-enhanced/location/Sydney\n\n# Test with countries (will return data for capital or major city)\ncurl http://localhost:4000/v1/weather-enhanced/location/Japan\ncurl http://localhost:4000/v1/weather-enhanced/location/Australia\n\n# Test coordinates endpoints\ncurl http://localhost:4000/v1/weather/coordinates/51.5074/-0.1276\ncurl http://localhost:4000/v1/weather-enhanced/coordinates/40.7128/-74.0060\n\n# Test city ID endpoints\ncurl http://localhost:4000/v1/weather/id/3435910\ncurl http://localhost:4000/v1/weather-enhanced/id/2643743\n\n# Test city IDs search endpoints\ncurl http://localhost:4000/v1/info/city-ids/London\ncurl http://localhost:4000/v1/info/city-ids/Paris/FR\ncurl http://localhost:4000/v1/info/city-ids/New%20York/US/3\n\n\n# NEW: Test different forecast endpoints (not following weather patterns)\n# Test forecast by time intervals\ncurl http://localhost:4000/v1/forecast/interval/London/6h\ncurl http://localhost:4000/v1/forecast-enhanced/interval/London/12h\n\n# Test forecast by specific days\ncurl http://localhost:4000/v1/forecast/days/Paris/3\ncurl http://localhost:4000/v1/forecast-enhanced/days/Paris/5\n\n# Test forecast by time periods\ncurl http://localhost:4000/v1/forecast/hourly/Tokyo/morning\ncurl http://localhost:4000/v1/forecast-enhanced/hourly/Tokyo/afternoon\n```\n\n#### Testing with Postman\n\n1.  **Basic Weather:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/weather/location/London`\n\n2.  **Enhanced Weather:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/weather-enhanced/location/London`\n\n3.  **Basic Weather by Coordinates:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/weather/coordinates/51.5074/-0.1276`\n\n4.  **Enhanced Weather by Coordinates:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/weather-enhanced/coordinates/40.7128/-74.0060`\n\n5.  **Basic Weather by City ID:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/weather/id/3435910`\n\n6.  **Enhanced Weather by City ID:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/weather-enhanced/id/2643743`\n\n7.  **Search City IDs:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/info/city-ids/London`\n\n8.  **Search City IDs with Country:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/info/city-ids/Paris/FR`\n\n9.  **Search City IDs with Limit:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/info/city-ids/New%20York/US/3`\n\n\u003c/details\u003e\n\n\n### 2.4) Forecast Endpoints [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n\u003cbr\u003e\n\nThis section describes all forecast endpoints implemented in the microservice, including valid values, validations, usage examples, and unique characteristics for meteorological forecasts.\n\n***\n\n## 📊 Endpoint Comparison\n\n| Endpoint | Parameters | Use Case | Example |\n|----------|------------|----------|---------|\n| `/v1/forecast/interval/{location}/{interval}` | City + Interval | Forecast by specific intervals | London, 6h |\n| `/v1/forecast-enhanced/interval/{location}/{interval}` | City + Interval | Enhanced forecast by intervals | London, 12h |\n| `/v1/forecast/days/{location}/{days}` | City + Days | Forecast for specific days | Paris, 3 |\n| `/v1/forecast-enhanced/days/{location}/{days}` | City + Days | Enhanced forecast by days | Paris, 5 |\n| `/v1/forecast/hourly/{location}/{hour}` | City + Period | Forecast by day periods | Tokyo, morning |\n| `/v1/forecast-enhanced/hourly/{location}/{hour}` | City + Period | Enhanced forecast by periods | Tokyo, afternoon |\n| `/v1/forecast/events/{location}/{eventType}` | City + Event | Forecast by event types | Madrid, weekend |\n| `/v1/forecast-enhanced/events/{location}/{eventType}` | City + Event | Enhanced forecast by events | Madrid, vacation |\n| `/v1/forecast/compare/{location}/{period1}/{period2}` | City + Periods | Comparison between periods | London, today/tomorrow |\n| `/v1/forecast-enhanced/compare/{location}/{period1}/{period2}` | City + Periods | Enhanced comparison between periods | London, afternoon/night |\n| `/v1/forecast/weekly/{location}/{weeks}` | City + Weeks | Forecast grouped by weeks | Paris, 2 |\n| `/v1/forecast-enhanced/weekly/{location}/{weeks}` | City + Weeks | Enhanced forecast by weeks | Madrid, 1 |\n\n\n## 1. By Time Intervals\n\n**Basic Endpoint**\n\n    GET /v1/forecast/interval/{location}/{interval}\n\n**Description**: Get forecast data filtered by specific time intervals\n**Parameters**:\n\n*   `location`: City name (e.g., \"London\", \"Buenos Aires\")\n*   `interval`: Time interval (`3h`, `6h`, `12h`, `24h`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast/interval/London/6h\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/forecast?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-interval.js`\n\n**Unique Features**:\n\n*   Filters forecast data by specific intervals\n*   Reduces the amount of data returned according to the requested interval\n*   Provides trend analysis by interval\n\n### 1.1. Enhanced by Time Intervals\n\n**Enhanced Endpoint**\n\n    GET /v1/forecast-enhanced/interval/{location}/{interval}\n\n**Description**: Get enriched forecast data by specific time intervals\n**Parameters**:\n\n*   `location`: City name (e.g., \"London\", \"Buenos Aires\")\n*   `interval`: Time interval (`3h`, `6h`, `12h`, `24h`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast-enhanced/interval/London/12h\n```\n\n**Controller**: `get-by-interval-enhanced.js`\n\n**Additional Features**:\n\n*   Trend analysis by interval\n*   Specific recommendations per period\n*   Statistical summary of the interval\n*   Temperature and unit conversions\n\n***\n\n## 2. By Specific Days\n\n**Basic Endpoint**\n\n    GET /v1/forecast/days/{location}/{days}\n\n**Description**: Get forecast data for a specific number of days\n**Parameters**:\n\n*   `location`: City name (e.g., \"Paris\", \"Tokyo\")\n*   `days`: Number of days (1-5)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast/days/Paris/3\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/forecast?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-days.js`\n\n**Unique Features**:\n\n*   Filters forecast by specific number of days\n*   Generates daily summary with averages\n*   Identifies predominant conditions per day\n*   Calculates daily temperature ranges\n\n### 2.1. Enhanced by Specific Days\n\n**Enhanced Endpoint**\n\n    GET /v1/forecast-enhanced/days/{location}/{days}\n\n**Description**: Get enriched forecast data for specific days\n**Parameters**:\n\n*   `location`: City name (e.g., \"Paris\", \"Tokyo\")\n*   `days`: Number of days (1-5)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast-enhanced/days/Paris/5\n```\n\n**Controller**: `get-by-days-enhanced.js`\n\n**Additional Features**:\n\n*   Day-to-day variation analysis\n*   Recommendations for extended periods\n*   Long-term temperature trends\n*   Activity planning per day\n\n***\n\n## 3. By Time Periods\n\n**Basic Endpoint**\n\n    GET /v1/forecast/hourly/{location}/{hour}\n\n**Description**: Get forecast data filtered by specific time periods\n**Parameters**:\n\n*   `location`: City name (e.g., \"Tokyo\", \"New York\")\n*   `hour`: Time period (`morning`, `afternoon`, `evening`, `night`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast/hourly/Tokyo/morning\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/forecast?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-hourly.js`\n\n**Unique Features**:\n\n*   Filters forecast by day periods\n*   Morning: 06:00-11:59\n*   Afternoon: 12:00-17:59\n*   Evening: 18:00-21:59\n*   Night: 22:00-05:59\n*   Specific recommendations per period\n\n### 3.1. Enhanced by Time Periods\n\n**Enhanced Endpoint**\n\n    GET /v1/forecast-enhanced/hourly/{location}/{hour}\n\n**Description**: Get enriched forecast data by time periods\n**Parameters**:\n\n*   `location`: City name (e.g., \"Tokyo\", \"New York\")\n*   `hour`: Time period (`morning`, `afternoon`, `evening`, `night`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast-enhanced/hourly/Tokyo/afternoon\n```\n\n**Controller**: `get-by-hourly-enhanced.js`\n\n**Additional Features**:\n\n*   Specific analysis by day period\n*   Personalized recommendations per hour\n*   Wind and humidity analysis by period\n*   Activity suggestions by time of day\n\n***\n\n## 4. By Events\n\n**Basic Endpoint**\n\n    GET /v1/forecast/events/{location}/{eventType}\n\n**Description**: Get forecast data filtered by specific event types\n**Parameters**:\n\n*   `location`: City name (e.g., \"Madrid\", \"Buenos Aires\")\n*   `eventType`: Event type (`weekend`, `holiday`, `workday`, `vacation`, `party`, `sports`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast/events/Madrid/weekend\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/forecast?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-events.js`\n\n**Unique Features**:\n\n*   Filters forecast according to specific event types\n*   Weekend: Saturdays and Sundays\n*   Holiday: holidays\n*   Workday: work days\n*   Vacation: vacation periods\n*   Party: social events\n*   Sports: sporting events\n\n### 4.1. Enhanced by Events\n\n**Enhanced Endpoint**\n\n    GET /v1/forecast-enhanced/events/{location}/{eventType}\n\n**Description**: Get enriched forecast data by event types\n**Parameters**:\n\n*   `location`: City name (e.g., \"Madrid\", \"Buenos Aires\")\n*   `eventType`: Event type (`weekend`, `holiday`, `workday`, `vacation`, `party`, `sports`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast-enhanced/events/Madrid/vacation\n```\n\n**Controller**: `get-by-events-enhanced.js`\n\n**Additional Features**:\n\n*   Specific analysis by event type\n*   Personalized recommendations according to the event\n*   Activity planning by event type\n*   Clothing and equipment suggestions\n\n***\n\n## 5. Period Comparison\n\n**Basic Endpoint**\n\n    GET /v1/forecast/compare/{location}/{period1}/{period2}\n\n**Description**: Compare forecast data between two specific periods\n**Parameters**:\n\n*   `location`: City name (e.g., \"London\", \"Buenos Aires\")\n*   `period1`, `period2`: Periods to compare (`today`, `tomorrow`, `weekend`, `next_week`, `morning`, `afternoon`, `evening`, `night`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast/compare/London/today/tomorrow\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/forecast?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-compare.js`\n\n**Unique Features**:\n\n*   Compares forecasts between specific periods\n*   Temperature difference analysis\n*   Meteorological condition comparison\n*   Trend identification between periods\n\n### 5.1. Enhanced Period Comparison\n\n**Enhanced Endpoint**\n\n    GET /v1/forecast-enhanced/compare/{location}/{period1}/{period2}\n\n**Description**: Compare enriched forecast data between specific periods\n**Parameters**:\n\n*   `location`: City name (e.g., \"London\", \"Buenos Aires\")\n*   `period1`, `period2`: Periods to compare (`today`, `tomorrow`, `weekend`, `next_week`, `morning`, `afternoon`, `evening`, `night`)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast-enhanced/compare/London/afternoon/night\n```\n\n**Controller**: `get-by-compare-enhanced.js`\n\n**Additional Features**:\n\n*   Detailed analysis of differences between periods\n*   Recommendations based on comparisons\n*   Change trends between periods\n*   Strategic planning based on comparisons\n\n***\n\n## 6. By Weeks\n\n**Basic Endpoint**\n\n    GET /v1/forecast/weekly/{location}/{weeks}\n\n**Description**: Get forecast data grouped by weeks\n**Parameters**:\n\n*   `location`: City name (e.g., \"Paris\", \"Madrid\")\n*   `weeks`: Number of weeks (1-4) - Note: the base API provides up to 5 days; the endpoint groups by weekly windows over that data\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast/weekly/Paris/2\n```\n\n**OpenWeatherMap URL**: `https://api.openweathermap.org/data/2.5/forecast?q={city}\u0026appid={API_KEY}`\n\n**Controller**: `get-by-weekly.js`\n\n**Unique Features**:\n\n*   Groups forecasts by weekly windows\n*   Weekly trend analysis\n*   Weekly condition summary\n*   Medium-term planning\n\n### 6.1. Enhanced by Weeks\n\n**Enhanced Endpoint**\n\n    GET /v1/forecast-enhanced/weekly/{location}/{weeks}\n\n**Description**: Get enriched forecast data grouped by weeks\n**Parameters**:\n\n*   `location`: City name (e.g., \"Paris\", \"Madrid\")\n*   `weeks`: Number of weeks (1-4)\n\n**Example**:\n\n```bash\ncurl http://localhost:4000/v1/forecast-enhanced/weekly/Madrid/1\n```\n\n**Controller**: `get-by-weekly-enhanced.js`\n\n**Additional Features**:\n\n*   Advanced weekly trend analysis\n*   Weekly planning recommendations\n*   Inter-week comparison\n*   Medium-term planning strategies\n\n\n***\n\n## 🔧 Common Features\n\nAll forecast endpoints include:\n\n### ✅ Parameter Validation\n\n*   City name validation\n*   Valid interval validation (`3h`, `6h`, `12h`, `24h`)\n*   Days validation (1-5)\n*   Time period validation (`morning`, `afternoon`, `evening`, `night`)\n*   Event type validation (`weekend`, `holiday`, `workday`, `vacation`, `party`, `sports`)\n*   Comparison period validation\n*   Weeks validation (1-4)\n\n### 💾 Smart Caching\n\n*   10-minute cache to reduce API calls\n*   Specific cache keys per endpoint type\n*   Automatic cache invalidation\n\n### 📁 Data Persistence\n\n*   Automatic JSON file saving\n*   Organized structure by endpoint type\n*   Backup data for analysis\n\n### 🔄 Asynchronous Processing\n\n*   Immediate response to user\n*   Background data saving\n*   Robust error handling\n\n***\n\n## 🎯 Specific Use Cases\n\n### Time Intervals\n\n*   **Planning applications**: For events that require forecasts every 6 or 12 hours\n*   **Industrial monitoring**: For processes that need data every 3 hours\n*   **Agriculture**: For irrigation and crop care every 24 hours\n\n### Specific Days\n\n*   **Travel planning**: To know the weather for the next 3 days\n*   **Sporting events**: To prepare outdoor activities\n*   **Construction**: To plan work according to expected weather\n\n### Time Periods\n\n*   **Commuters**: To know the morning weather before leaving\n*   **Recreational activities**: To plan activities according to the time of day\n*   **Commerce**: To adjust inventories according to expected weather\n\n### Events\n\n*   **Event planning**: To know the weather during weekends or vacations\n*   **Sports**: To plan sporting activities according to conditions\n*   **Tourism**: To optimize tourist activities\n\n### Comparisons\n\n*   **Decision making**: To compare conditions between periods\n*   **Strategic planning**: To choose the best time for activities\n*   **Trend analysis**: To identify weather patterns\n\n### Weeks\n\n*   **Medium-term planning**: For activities that require several days\n*   **Project management**: To plan work according to weekly weather\n*   **Trend analysis**: To identify weekly weather patterns\n\n***\n\n## 🚀 Response Examples\n\n### 6-hour interval\n\n```json\n{\n  \"forecast\": {\n    \"interval\": \"6h\",\n    \"filteredData\": [...],\n    \"totalEntries\": 8,\n    \"originalEntries\": 40,\n    \"intervalAnalysis\": {\n      \"summary\": \"6h forecast analysis for 8 periods\",\n      \"averageTemperature\": \"15.2\",\n      \"trends\": [...],\n      \"recommendations\": [...]\n    }\n  }\n}\n```\n\n### 3 specific days\n\n```json\n{\n  \"forecast\": {\n    \"days\": 3,\n    \"dailySummary\": [\n      {\n        \"day\": 1,\n        \"date\": \"2024-01-15\",\n        \"averageTemperature\": \"12.5\",\n        \"predominantCondition\": \"Clouds\"\n      }\n    ]\n  }\n}\n```\n\n### Morning period\n\n```json\n{\n  \"forecast\": {\n    \"hour\": \"morning\",\n    \"hourlySummary\": {\n      \"summary\": \"morning forecast summary\",\n      \"averageTemperature\": \"8.3\",\n      \"timeRange\": {\"start\": \"06:00\", \"end\": \"11:59\"}\n    }\n  }\n}\n```\n\n### Period comparison\n\n```json\n{\n  \"forecast\": {\n    \"comparison\": {\n      \"period1\": \"today\",\n      \"period2\": \"tomorrow\",\n      \"temperatureDifference\": \"+2.3\",\n      \"conditionComparison\": \"Similar conditions expected\",\n      \"recommendations\": [...]\n    }\n  }\n}\n```\n***\n\n## 📝 Important Notes\n\n1.  **API Key**: All endpoints require a valid OpenWeatherMap API key\n2.  **Rate Limits**: Respect API limits (1000 calls/day on free plan)\n3.  **Activation**: New API keys take up to 2 hours to activate\n4.  **Cache**: Data is cached for 10 minutes to optimize performance\n5.  **Storage**: Data is automatically saved to JSON files\n6.  **URL-encoding**: Encode spaces/accents, for example `La%20Plata`\n7.  **Errors**: If there's no data for the requested range/period, returns 400 with details\n8.  **Enhanced**: Adds summaries, trends, recommendations and metadata\n9.  **Source**: OpenWeather `data/2.5/forecast` (5 days, 3h intervals)\n10. **Units**: Default Kelvin; several endpoints use `metric`\n\n***\n\n## 🔗 References\n\n*   [OpenWeatherMap API Documentation](https://openweathermap.org/api)\n*   [5-day/3-hour Forecast API](https://openweathermap.org/forecast5)\n*   [Weather API Endpoints](https://openweathermap.org/api/weather-data)\n*   [Forecast Data Format](https://openweathermap.org/forecast5#data)\n\n\u003c/details\u003e\n\n\n\n### 2.5) Forecast Examples [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\u003cbr\u003e\n\n#### Basic Forecast by Time Intervals\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast/interval/London/6h\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"interval\": \"6h\",\n      \"location\": \"London\",\n      \"filteredData\": [\n        {\n          \"dt\": 1705320000,\n          \"main\": {\n            \"temp\": 275.15,\n            \"feels_like\": 272.84,\n            \"pressure\": 1013,\n            \"humidity\": 85\n          },\n          \"weather\": [\n            {\n              \"id\": 500,\n              \"main\": \"Rain\",\n              \"description\": \"light rain\"\n            }\n          ],\n          \"dt_txt\": \"2024-01-15 12:00:00\"\n        }\n      ],\n      \"totalEntries\": 8,\n      \"originalEntries\": 40,\n      \"intervalAnalysis\": {\n        \"summary\": \"6h forecast analysis for 8 periods\",\n        \"averageTemperature\": \"15.2\",\n        \"trends\": [\"increasing\", \"stable\"],\n        \"recommendations\": [\"Bring an umbrella\", \"Wear warm clothing\"]\n      }\n    }\n  }\n}\n```\n\n#### Enhanced Forecast by Time Intervals\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast-enhanced/interval/London/12h\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"interval\": \"12h\",\n      \"location\": \"London\",\n      \"filteredData\": [...],\n      \"totalEntries\": 4,\n      \"originalEntries\": 40,\n      \"intervalAnalysis\": {\n        \"summary\": \"12h forecast analysis for 4 periods\",\n        \"averageTemperature\": \"12.8\",\n        \"temperatureRange\": {\"min\": 8.5, \"max\": 17.2},\n        \"trends\": [\"gradual warming\", \"stable conditions\"],\n        \"recommendations\": [\"Perfect for outdoor activities\", \"Light jacket recommended\"],\n        \"statistics\": {\n          \"temperatureVariance\": 8.7,\n          \"humidityAverage\": 78,\n          \"pressureTrend\": \"stable\"\n        }\n      },\n      \"enhancedFeatures\": {\n        \"temperatureConversions\": {\n          \"kelvin\": 285.95,\n          \"celsius\": 12.8,\n          \"fahrenheit\": 55.04\n        },\n        \"comfortAnalysis\": {\n          \"index\": 7.2,\n          \"level\": \"comfortable\"\n        },\n        \"activityRecommendations\": {\n          \"morning\": \"Great for jogging\",\n          \"afternoon\": \"Perfect for picnics\",\n          \"evening\": \"Ideal for outdoor dining\"\n        }\n      }\n    }\n  }\n}\n```\n\n#### Forecast by Specific Days\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast/days/Paris/3\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"days\": 3,\n      \"location\": \"Paris\",\n      \"dailySummary\": [\n        {\n          \"day\": 1,\n          \"date\": \"2024-01-15\",\n          \"averageTemperature\": \"12.5\",\n          \"temperatureRange\": {\"min\": 8.2, \"max\": 16.8},\n          \"predominantCondition\": \"Clouds\",\n          \"humidity\": 75,\n          \"windSpeed\": 3.2,\n          \"recommendation\": \"Light jacket recommended\"\n        },\n        {\n          \"day\": 2,\n          \"date\": \"2024-01-16\",\n          \"averageTemperature\": \"14.1\",\n          \"temperatureRange\": {\"min\": 10.5, \"max\": 18.3},\n          \"predominantCondition\": \"Clear\",\n          \"humidity\": 68,\n          \"windSpeed\": 2.8,\n          \"recommendation\": \"Perfect weather for outdoor activities\"\n        },\n        {\n          \"day\": 3,\n          \"date\": \"2024-01-17\",\n          \"averageTemperature\": \"11.8\",\n          \"temperatureRange\": {\"min\": 7.9, \"max\": 15.6},\n          \"predominantCondition\": \"Rain\",\n          \"humidity\": 82,\n          \"windSpeed\": 4.1,\n          \"recommendation\": \"Bring an umbrella and raincoat\"\n        }\n      ],\n      \"overallTrend\": \"Slightly cooling trend with increasing humidity\"\n    }\n  }\n}\n```\n\n#### Forecast by Time Periods (Morning)\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast/hourly/Tokyo/morning\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"hour\": \"morning\",\n      \"location\": \"Tokyo\",\n      \"hourlySummary\": {\n        \"summary\": \"morning forecast summary\",\n        \"averageTemperature\": \"8.3\",\n        \"temperatureRange\": {\"min\": 6.1, \"max\": 11.2},\n        \"timeRange\": {\"start\": \"06:00\", \"end\": \"11:59\"},\n        \"predominantCondition\": \"Clear\",\n        \"humidity\": 65,\n        \"windSpeed\": 2.5,\n        \"visibility\": 10000,\n        \"recommendations\": [\"Perfect for morning jogging\", \"Light layers recommended\"]\n      },\n      \"morningActivities\": {\n        \"outdoor\": \"Excellent conditions\",\n        \"commute\": \"Clear visibility, comfortable temperature\",\n        \"exercise\": \"Ideal for outdoor workouts\"\n      }\n    }\n  }\n}\n```\n\n#### Forecast by Events (Weekend)\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast/events/Madrid/weekend\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"eventType\": \"weekend\",\n      \"location\": \"Madrid\",\n      \"eventSummary\": {\n        \"summary\": \"Weekend forecast for Madrid\",\n        \"dateRange\": \"2024-01-13 to 2024-01-14\",\n        \"averageTemperature\": \"16.5\",\n        \"temperatureRange\": {\"min\": 12.3, \"max\": 20.8},\n        \"predominantCondition\": \"Partly Cloudy\",\n        \"humidity\": 58,\n        \"windSpeed\": 3.7,\n        \"recommendation\": \"Great weekend weather for outdoor activities\"\n      },\n      \"weekendActivities\": {\n        \"saturday\": {\n          \"morning\": \"Perfect for brunch outdoors\",\n          \"afternoon\": \"Ideal for park visits\",\n          \"evening\": \"Great for outdoor dining\"\n        },\n        \"sunday\": {\n          \"morning\": \"Excellent for family walks\",\n          \"afternoon\": \"Perfect for outdoor sports\",\n          \"evening\": \"Comfortable for evening strolls\"\n        }\n      },\n      \"eventRecommendations\": [\n        \"Visit Retiro Park\",\n        \"Outdoor dining in Plaza Mayor\",\n        \"Walking tour of historic center\",\n        \"Picnic in Casa de Campo\"\n      ]\n    }\n  }\n}\n```\n\n#### Forecast Period Comparison\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast/compare/London/today/tomorrow\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"comparison\": {\n        \"period1\": \"today\",\n        \"period2\": \"tomorrow\",\n        \"location\": \"London\",\n        \"temperatureDifference\": \"+2.3\",\n        \"humidityDifference\": \"-8\",\n        \"windDifference\": \"+1.2\",\n        \"conditionComparison\": \"Similar conditions expected\",\n        \"detailedComparison\": {\n          \"today\": {\n            \"averageTemp\": 8.5,\n            \"humidity\": 78,\n            \"windSpeed\": 3.2,\n            \"condition\": \"Cloudy\",\n            \"precipitation\": \"20%\"\n          },\n          \"tomorrow\": {\n            \"averageTemp\": 10.8,\n            \"humidity\": 70,\n            \"windSpeed\": 4.4,\n            \"condition\": \"Partly Cloudy\",\n            \"precipitation\": \"15%\"\n          }\n        },\n        \"recommendations\": [\n          \"Tomorrow will be slightly warmer\",\n          \"Lower humidity makes it more comfortable\",\n          \"Slightly windier conditions expected\",\n          \"Better visibility tomorrow\"\n        ],\n        \"trendAnalysis\": \"Improving conditions with warming trend\"\n      }\n    }\n  }\n}\n```\n\n#### Forecast by Weeks\n\n**Request:**\n\n```bash\nGET http://localhost:4000/v1/forecast/weekly/Paris/2\n```\n\n**Response:**\n\n```json\n{\n  \"statusCode\": 200,\n  \"body\": {\n    \"forecast\": {\n      \"weeks\": 2,\n      \"location\": \"Paris\",\n      \"weeklySummary\": [\n        {\n          \"week\": 1,\n          \"dateRange\": \"2024-01-15 to 2024-01-19\",\n          \"averageTemperature\": \"13.2\",\n          \"temperatureRange\": {\"min\": 9.1, \"max\": 17.8},\n          \"predominantCondition\": \"Partly Cloudy\",\n          \"precipitationChance\": \"25%\",\n          \"humidity\": 72,\n          \"windSpeed\": 3.8,\n          \"recommendation\": \"Good week for outdoor activities\"\n        },\n        {\n          \"week\": 2,\n          \"dateRange\": \"2024-01-22 to 2024-01-26\",\n          \"averageTemperature\": \"11.8\",\n          \"temperatureRange\": {\"min\": 7.5, \"max\": 16.2},\n          \"predominantCondition\": \"Rain\",\n          \"precipitationChance\": \"45%\",\n          \"humidity\": 78,\n          \"windSpeed\": 4.2,\n          \"recommendation\": \"Prepare for wetter conditions\"\n        }\n      ],\n      \"interWeekComparison\": {\n        \"temperatureTrend\": \"Cooling trend\",\n        \"humidityTrend\": \"Increasing\",\n        \"precipitationTrend\": \"Higher chance of rain\",\n        \"overallAssessment\": \"Weather becoming more unsettled\"\n      },\n      \"weeklyPlanning\": {\n        \"week1\": \"Ideal for outdoor activities and sightseeing\",\n        \"week2\": \"Plan indoor activities and bring rain gear\"\n      }\n    }\n  }\n}\n```\n\n#### Testing with curl\n\n```bash\n# Test basic forecast endpoints\ncurl http://localhost:4000/v1/forecast/interval/London/6h\ncurl http://localhost:4000/v1/forecast/days/Paris/3\ncurl http://localhost:4000/v1/forecast/hourly/Tokyo/morning\n\n# Test enhanced forecast endpoints\ncurl http://localhost:4000/v1/forecast-enhanced/interval/London/12h\ncurl http://localhost:4000/v1/forecast-enhanced/days/Paris/5\ncurl http://localhost:4000/v1/forecast-enhanced/hourly/Tokyo/afternoon\n\n# Test forecast by events\ncurl http://localhost:4000/v1/forecast/events/Madrid/weekend\ncurl http://localhost:4000/v1/forecast-enhanced/events/New%20York/vacation\n\n# Test forecast comparisons\ncurl http://localhost:4000/v1/forecast/compare/London/today/tomorrow\ncurl http://localhost:4000/v1/forecast-enhanced/compare/Berlin/morning/evening\n\n# Test forecast by weeks\ncurl http://localhost:4000/v1/forecast/weekly/Paris/2\ncurl http://localhost:4000/v1/forecast-enhanced/weekly/Madrid/1\n```\n\n#### Testing with Postman\n\n1.  **Basic Forecast by Intervals:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast/interval/London/6h`\n\n2.  **Enhanced Forecast by Intervals:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast-enhanced/interval/London/12h`\n\n3.  **Basic Forecast by Days:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast/days/Paris/3`\n\n4.  **Enhanced Forecast by Days:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast-enhanced/days/Paris/5`\n\n5.  **Basic Forecast by Time Periods:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast/hourly/Tokyo/morning`\n\n6.  **Enhanced Forecast by Time Periods:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast-enhanced/hourly/Tokyo/afternoon`\n\n7.  **Basic Forecast by Events:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast/events/Madrid/weekend`\n\n8.  **Enhanced Forecast by Events:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast-enhanced/events/New%20York/vacation`\n\n9.  **Basic Forecast Comparison:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast/compare/London/today/tomorrow`\n\n10. **Enhanced Forecast Comparison:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast-enhanced/compare/Berlin/morning/evening`\n\n11. **Basic Forecast by Weeks:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast/weekly/Paris/2`\n\n12. **Enhanced Forecast by Weeks:**\n    *   Method: `GET`\n    *   URL: `http://localhost:4000/v1/forecast-enhanced/weekly/Madrid/1`\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Section 3) Data Persistence and Storage [🔝](#index-)\n\n### 3.1) Storage Architecture \u0026 Structure [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n\u003cbr\u003e\n\n### 📁 Storage Architecture Overview\n\nThe microservice implements a **multi-layered storage architecture** with intelligent caching and persistence strategies.\n\n### 🏗️ Storage Locations \u0026 Structure\n\n    src/data/json/\n    ├── weather/\n    │   ├── weather-data.json              # Basic weather data\n    │   └── weather-enhanced-data.json     # Enhanced weather data\n    ├── forecast/\n    │   ├── forecast-interval-data.json           # Forecast by intervals data\n    │   ├── forecast-interval-enhanced-data.json  # Enhanced forecast by intervals data\n    │   ├── forecast-days-data.json               # Forecast by days data\n    │   ├── forecast-days-enhanced-data.json      # Enhanced forecast by days data\n    │   ├── forecast-hourly-data.json             # Forecast by hourly periods data\n    │   ├── forecast-hourly-enhanced-data.json    # Enhanced forecast by hourly periods data\n    │   ├── forecast-weekly-data.json             # Forecast by weeks data\n    │   ├── forecast-weekly-enhanced-data.json    # Enhanced forecast by weeks data\n    │   ├── forecast-events-data.json             # Forecast by events data\n    │   ├── forecast-events-enhanced-data.json    # Enhanced forecast by events data\n    │   ├── forecast-compare-data.json            # Forecast comparison data\n    │   └── forecast-compare-enhanced-data.json   # Enhanced forecast comparison data\n    └── weather-condition/\n        └── (weather condition data)\n\n### 🔄 Dual-Layer Caching Strategy\n\nThe microservice implements a **dual-layer caching strategy**:\n\n1.  **Memory Cache**: Fast in-memory cache for frequently accessed data\n    *   **Duration**: 10 minutes for weather data\n    *   **Storage**: RAM-based for ultra-fast access\n    *   **Eviction**: Automatic cleanup of expired entries\n\n2.  **JSON File Storage**: Persistent storage for backup and debugging\n    *   **Duration**: Permanent until overwritten\n    *   **Storage**: File system for data persistence\n    *   **Purpose**: Backup, debugging, and development reference\n\n### 🔄 Data Flow \u0026 Processing\n\n    API Request → Check Memory Cache → If not found → Call OpenWeather API → Store in Memory Cache → Save to JSON File (async) → Return Response Immediately\n\n**Processing Steps:**\n1.  **API Call**: When an endpoint is called, the microservice fetches data from OpenWeather API\n2.  **Data Processing**: The response is processed and transformed (if enhanced endpoint)\n3.  **Async JSON Storage**: The processed data is automatically saved to the corresponding JSON file **asynchronously** (non-blocking)\n4.  **Immediate Response**: The data is returned to the client immediately, without waiting for file write completion\n\n### ✅ Key Benefits\n\n*   **🔍 Debugging**: Easy access to recent API responses for troubleshooting\n*   **📊 Data Analysis**: Historical data for analysis and development\n*   **🛡️ Backup**: Local backup of API responses in case of external API issues\n*   **⚡ Development**: Faster development and testing with local data access\n*   **🚀 Performance**: Reduces API calls through intelligent caching system\n\n### 📝 File Management\n\n*   **Automatic Updates**: Files are updated with each successful API call\n*   **Overwrite Policy**: Each new request overwrites the previous data\n*   **Non-Blocking Writes**: JSON files are written asynchronously to avoid blocking API responses\n*   **Error Handling**: If file creation fails, the API still returns data to the client (with warning logs)\n*   **Storage Location**: Files are stored in the `src/data/json/` directory structure\n*   **Enhanced Endpoints**: All enhanced endpoints now save their transformed data to separate JSON files\n\n### 📄 Example File Structure\n\n```json\n// src/data/json/weather/weather-data.json\n{\n    \"coord\": {\"lon\": -58.3772, \"lat\": -34.6132},\n    \"weather\": [{\"id\": 804, \"main\": \"Clouds\", \"description\": \"overcast clouds\"}],\n    \"main\": {\n        \"temp\": 290.25,\n        \"feels_like\": 290.24,\n        \"pressure\": 1012,\n        \"humidity\": 85\n    },\n    \"name\": \"Buenos Aires\",\n    \"cod\": 200\n}\n```\n\n\u003c/details\u003e\n\n### 3.2) Advanced Features \u0026 Performance [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n\u003cbr\u003e\n\n### 📊 Data Analytics and Monitoring\n\nThe storage system includes comprehensive analytics capabilities:\n\n*   **Usage Tracking**: Monitor API call patterns and frequency\n*   **Performance Metrics**: Track response times and cache hit rates\n*   **Error Logging**: Detailed error tracking with timestamps\n*   **Data Quality**: Validation and quality checks on stored data\n\n### 🛡️ Data Security and Privacy\n\n*   **Encryption**: Sensitive data is encrypted at rest\n*   **Access Control**: Role-based access to stored data\n*   **Data Retention**: Automatic cleanup of old data based on policies\n*   **Privacy Compliance**: GDPR and privacy regulation compliance\n\n### 🔄 Data Synchronization\n\n*   **Real-time Sync**: Immediate synchronization between cache layers\n*   **Conflict Resolution**: Automatic handling of data conflicts\n*   **Backup Verification**: Regular verification of backup integrity\n*   **Recovery Procedures**: Automated disaster recovery processes\n\n### ⚡ Performance Metrics\n\n| **Metric** | **Value** | **Impact** |\n|------------|-----------|------------|\n| Memory Cache Hit Rate | 85-95% | Ultra-fast response times |\n| File Cache Hit Rate | 70-80% | Reduced API calls |\n| Average Response Time | \u003c200ms | Improved user experience |\n| API Call Reduction | 60-70% | Cost savings and reliability |\n\n### 🚀 Optimization Strategies\n\n1. **Smart Cache Keys**: Intelligent key generation for optimal cache utilization\n2. **Predictive Caching**: Pre-load frequently requested data\n3. **Compression**: Data compression for storage efficiency\n4. **Batch Operations**: Optimized batch processing for bulk operations\n\n### 📋 Debugging and Troubleshooting\n\n**Debug Information Available:**\n*   **Request/Response Logs**: Complete request and response logging\n*   **Cache Status**: Real-time cache status and statistics\n*   **Error Traces**: Detailed error traces with stack information\n*   **Performance Profiling**: Detailed performance analysis\n\n**Troubleshooting Tools:**\n*   **Health Check Endpoints**: Monitor storage system health\n*   **Cache Invalidation**: Manual cache clearing capabilities\n*   **Data Validation**: Automated data integrity checks\n*   **Recovery Tools**: Built-in recovery and repair utilities\n\n\u003c/details\u003e\n\n### 3.3) Best Practices \u0026 Future Roadmap [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n\u003cbr\u003e\n\n### ✅ Storage Best Practices\n\n**Recommended Practices:**\n*   **Regular Backups**: Automated daily backups of critical data\n*   **Monitoring**: Continuous monitoring of storage health\n*   **Testing**: Regular testing of backup and recovery procedures\n*   **Documentation**: Comprehensive documentation of storage procedures\n\n**Common Pitfalls to Avoid:**\n*   **Manual File Editing**: Never manually edit JSON cache files\n*   **Cache Staleness**: Avoid relying on stale cached data\n*   **Storage Overload**: Monitor storage space to prevent overload\n*   **Security Gaps**: Ensure proper access controls are in place\n\n### 🚀 Future Enhancements\n\n**Planned Improvements:**\n*   **Database Integration**: PostgreSQL/MySQL integration for production\n*   **Redis Cache**: Redis integration for distributed caching\n*   **Cloud Storage**: AWS S3 integration for scalable storage\n*   **Real-time Analytics**: Advanced analytics and reporting\n\n**Scalability Considerations:**\n*   **Horizontal Scaling**: Support for multiple instance deployment\n*   **Load Balancing**: Intelligent load balancing across instances\n*   **Data Partitioning**: Automatic data partitioning for large datasets\n*   **Cross-Region Sync**: Multi-region data synchronization\n\n### 📝 Important Notes\n\n\u003e **💡 Note**: The JSON files serve as a local cache and backup system. They are automatically managed by the microservice and should not be manually edited.\n\n\u003e **⚡ Performance Note**: JSON file writes are performed asynchronously to ensure fast API response times. The microservice returns data immediately without waiting for file operations to complete.\n\n\u003e **🔒 Security Note**: All stored data is encrypted and access-controlled. Regular security audits ensure compliance with best practices.\n\n\u003e **📊 Analytics Note**: The storage system provides comprehensive analytics and monitoring capabilities for optimal performance tracking.\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n\n## Section 4) Functionality Testing and References [🔝](#index-)\n\n### 4.1) Functionality test [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n\u003cbr\u003e\n\n\u003c/details\u003e\n\n### 4.2) References [🔝](#index-)\n\n\u003cdetails\u003e\n  \u003csummary\u003eView details\u003c/summary\u003e\n\n \u003cbr\u003e\n\n### 🌐 OpenWeatherMap API Resources\n\n#### Official Documentation\n*   [OpenWeatherMap API Documentation](https://openweathermap.org/api) - Complete API reference\n*   [OpenWeather API Keys Management](https://home.openweathermap.org/api_keys) - API key configuration\n*   [Weather API Endpoints](https://openweathermap.org/api/weather-data) - Current weather data\n*   [5-day/3-hour Forecast API](https://openweathermap.org/forecast5) - Forecast data\n*   [Weather Conditions Codes](https://openweathermap.org/weather-conditions) - Weather condition codes\n*   [Supported Languages](https://openweathermap.org/current#multi) - Available languages\n*   [Units Format](https://openweathermap.org/current#data) - Temperature and measurement units\n\n#### API Guides \u0026 Tutorials\n*   [OpenWeather Guide](https://openweathermap.org/guide) - Getting started guide\n*   [API FAQ](https://openweathermap.org/faq) - Frequently asked questions\n*   [Support Forum](https://openweathermap.org/forum) - Community support\n*   [Recommended Video Tutorial](https://www.youtube.com/watch?v=im7THL67z0c) - YouTube tutorial\n\n### ☁️ AWS Services \u0026 Infrastructure\n\n#### AWS Lambda\n*   [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/) - Official Lambda docs\n*   [Lambda Best Practices](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html) - Performance optimization\n*   [Lambda Environment Variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html) - Configuration management\n*   [Lambda Error Handling](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html) - Error management\n\n#### API Gateway\n*   [AWS API Gateway Documentation](https://docs.aws.amazon.com/apigateway/) - Complete API Gateway guide\n*   [Best API Gateway Practices](https://docs.aws.amazon.com/whitepapers/latest/best-practices-api-gateway-private-apis-integration/rest-api.html) - Best practices\n*   [Creating Custom API Keys](https://towardsaws.com/protect-your-apis-by-creating-api-keys-using-serverless-framework-fe662ad37447) - API key management\n*   [API Gateway Properties Configuration](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml) - Serverless configuration\n\n#### AWS Systems Manager\n*   [AWS SSM Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) - Parameter management\n*   [SSM Best Practices](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-best-practices.html) - Security and organization\n\n#### AWS Monitoring \u0026 Logging\n*   [AWS CloudWatch](https://docs.aws.amazon.com/cloudwatch/) - Monitoring and logging\n*   [CloudWatch Logs](https://docs.aws.amazon.com/cloudwatch/latest/logs/) - Log management\n*   [CloudWatch Metrics](https://docs.aws.amazon.com/cloudwatch/latest/monitoring/) - Performance metrics\n\n### 🚀 Serverless Framework\n\n#### Core Documentation\n*   [Serverless Framework Documentation](https://www.serverless.com/framework/docs/) - Complete framework guide\n*   [AWS Provider Guide](https://www.serverless.com/framework/docs/providers/aws/guide/) - AWS-specific configuration\n*   [Serverless Plugins](https://www.serverless.com/plugins) - Available plugins directory\n*   [Serverless Best Practices](https://www.serverless.com/framework/docs/providers/aws/guide/best-practices/) - Framework best practices\n\n#### Essential Plugins\n*   [serverless-offline](https://www.npmjs.com/package/serverless-offline) - Local development\n*   [serverless-offline-ssm](https://www.npmjs.com/package/serverless-offline-ssm) - Parameter Store simulation\n*   [serverless-auto-swagger](https://www.npmjs.com/package/serverless-auto-swagger) - API documentation\n*   [serverless-openapi-documentation](https://www.serverless.com/plugins/serverless-openapi-documentation) - OpenAPI docs\n\n### 🧪 Testing \u0026 Quality Assurance\n\n#### Jest Testing Framework\n*   [Jest Documentation](https://jestjs.io/docs/getting-started) - Complete testing guide\n*   [Jest Environment Variables](https://stackoverflow.com/questions/48033841/test-process-env-with-jest) - Environment setup\n*   [Jest Mocking](https://jestjs.io/docs/mock-functions) - Function mocking\n*   [Jest Async Testing](https://jestjs.io/docs/asynchronous) - Async test handling\n\n#### Supertest for API Testing\n*   [Supertest Documentation](https://github.com/visionmedia/supertest) - HTTP testing library\n*   [API Testing Best Practices](https://blog.postman.com/api-testing-best-practices/) - Testing strategies\n\n#### Code Quality Tools\n*   [ESLint Documentation](https://eslint.org/docs/latest/) - Code linting\n*   [Prettier Documentation](https://prettier.io/docs/en/) - Code formatting\n*   [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) - Best practices guide\n\n### 🛠️ Development Tools \u0026 Libraries\n\n#### Node.js \u0026 JavaScript\n*   [Node.js Documentation](https://nodejs.org/docs/) - Official Node.js docs\n*   [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices) - Development guidelines\n*   [JavaScript MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript) - JavaScript reference\n\n#### HTTP \u0026 API Libraries\n*   [Axios Documentation](https://axios-http.com/docs/intro) - HTTP client library\n*   [Lodash Documentation](https://lodash.com/docs/) - Utility library\n*   [Moment.js Documentation](https://momentjs.com/docs/) - Date manipulation\n*   [Joi Validation](https://joi.dev/api/) - Data validation\n\n#### Database \u0026 ORM\n*   [Sequelize Documentation](https://sequelize.org/docs/v6/) - SQL ORM for Node.js\n*   [Sequelize Models and Operators](https://sequelize.org/docs/v6/core-concepts/model-querying-basics/) - Query basics\n*   [MySQL with Node.js](https://jasonwatmore.com/post/2022/06/26/nodejs-mysql-connect-to-mysql-database-with-sequelize-mysql2) - Database connection\n\n### 🔧 Development Environment\n\n#### Visual Studio Code Extensions\n*   [Prettier Extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - Code formatting\n*   [ESLint Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - Code linting\n*   [YAML Extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - YAML support\n*   [Error Lens Extension](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens) - Error highlighting\n*   [Thunder Client](https://marketplace.visualstudio.com/items?itemName=rangav.vscode-thunder-client) - API testing\n\n#### API Testing Tools\n*   [Postman Documentation](https://learning.postman.com/docs/) - API testing platform\n*   [Thunder Client](https://marketplace.visualstudio.com/items?itemName=rangav.vscode-thunder-client) - VS Code API client\n*   [curl Manual](https://curl.se/docs/manual.html) - Command line HTTP client\n\n### 📊 Architecture \u0026 Design Tools\n\n#### Diagramming Tools\n*   [AWS Design Tool (draw.io)](https://app.diagrams.net/?splash=0\u0026libs=aws4) - Architecture diagrams\n*   [Mermaid.js](https://mermaid-js.github.io/mermaid/) - Markdown diagrams\n*   [Lucidchart](https://www.lucidchart.com/) - Professional diagramming\n\n#### Documentation Tools\n*   [Swagger/OpenAPI](https://swagger.io/docs/) - API documentation\n*   [Markdown Guide](https://www.markdownguide.org/) - Markdown syntax\n*   [GitBook](https://www.gitbook.com/) - Documentation platform\n\n### 🔐 Security \u0026 Best Practices\n\n#### API Security\n*   [OWASP API Security](https://owasp.org/www-project-api-security/) - API security guidelines\n*   [JWT Best Practices](https://tools.ietf.org/html/rfc8725) - Token security\n*   [API Rate Limiting](https://cloud.google.com/architecture/rate-limiting-strategies-techniques) - Rate limiting strategies\n\n#### AWS Security\n*   [AWS Security Best Practices](https://docs.aws.amazon.com/security/) - AWS security guide\n*   [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) - Identity management\n*   [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) - Architecture principles\n\n### 📚 Learning Resources\n\n#### Tutorials \u0026 Courses\n*   [AWS Serverless Workshop](https://serverlessland.com/workshops) - Hands-on learning\n*   [Node.js Tutorial](https://nodejs.org/en/learn/) - Official Node.js learning\n*   [JavaScript.info](https://javascript.info/) - Modern JavaScript tutorial\n*   [MDN Web Docs](https://developer.mozilla.org/) - Web development reference\n\n#### Community \u0026 Support\n*   [Stack Overflow](https://stackoverflow.com/questions/tagged/serverless) - Q\u0026A community\n*   [AWS Developer Forums](https://forums.aws.amazon.com/) - AWS community\n*   [Serverless Framework Community](https://forum.serverless.com/) - Framework community\n*   [GitHub Discussions](https://github.com/serverless/serverless/discussions) - GitHub community\n\n### 🌍 Additional APIs \u0026 Services\n\n#### Weather \u0026 Geographic APIs\n*   [OpenWeatherMap Forum](https://openweathermap.org/forum) - Community support\n*   [Weather API Alternatives](https://rapidapi.com/blog/weather-api-alternatives/) - Other weather APIs\n*   [Geocoding APIs](https://developers.google.com/maps/documentation/geocoding) - Location services\n\n#### Development APIs\n*   [MercadoLibre API](https://developers.mercadolibre.com.ar/es_ar/usuarios-y-aplicaciones) - E-commerce API\n*   [REST API Design](https://restfulapi.net/) - API design principles\n*   [HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) - Status code reference\n\n\u003cbr\u003e\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandresweitzel%2Fmicroservice_openweather_nodejs_jest_aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandresweitzel%2Fmicroservice_openweather_nodejs_jest_aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandresweitzel%2Fmicroservice_openweather_nodejs_jest_aws/lists"}