|
| 1 | +# 🌦️ WeatherBot |
| 2 | + |
| 3 | +This **WeatherBot** is a Telegram bot that provides users with real-time weather updates and personalized location-based forecasts. It is powered by the OpenWeatherMap API and offers a seamless experience for users to get weather information instantly. |
| 4 | + |
| 5 | +Additionally, the project includes an **admin control panel backend** for managing user preferences, locations, and bot functionality. |
| 6 | + |
| 7 | +Built with the lightweight and robust **grammY** framework for Telegram bot development, the bot is designed to handle user interactions efficiently, while the server handles data validation, persistence, and API integrations. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## Table of Contents |
| 12 | + |
| 13 | +- [Features](#features) |
| 14 | +- [Technologies Used](#technologies-used) |
| 15 | +- [Getting Started](#getting-started) |
| 16 | + - [Prerequisites](#prerequisites) |
| 17 | + - [Installation](#installation) |
| 18 | +- [Environment Variables](#environment-variables) |
| 19 | +- [Bot Commands](#bot-commands) |
| 20 | +- [API Endpoints](#api-endpoints) |
| 21 | + - [Location Validation](#location-validation) |
| 22 | + - [Get Weather](#get-weather) |
| 23 | +- [Contributing](#contributing) |
| 24 | +- [License](#license) |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## Features |
| 29 | + |
| 30 | +### Bot Features: |
| 31 | + |
| 32 | +- **Real-Time Weather Updates** |
| 33 | + Users can query the bot for live weather data, including temperature, humidity, and conditions. |
| 34 | + |
| 35 | +- **Personalized Location-Based Forecasts** |
| 36 | + Users can set their preferred locations and receive forecasts for those locations. |
| 37 | + |
| 38 | +- **Natural Language Interaction** |
| 39 | + Users can input city names, and the bot will validate and respond conversationally. |
| 40 | + |
| 41 | +### Admin Panel Features: |
| 42 | + |
| 43 | +- **Location Validation** |
| 44 | + Checks the validity of user-provided locations using OpenWeatherMap’s Geocoding API before saving them. |
| 45 | + |
| 46 | +- **User Management** |
| 47 | + Admins can view and manage user data and preferences through an intuitive control panel. |
| 48 | + |
| 49 | +- **Error Handling** |
| 50 | + Ensures smooth operation by handling invalid data, network issues, and API errors gracefully. |
| 51 | + |
| 52 | +--- |
| 53 | + |
| 54 | +## Technologies Used |
| 55 | + |
| 56 | +### Bot |
| 57 | +- **[grammY](https://grammy.dev/)**: A robust Telegram bot framework for handling bot interactions. |
| 58 | +- **OpenWeatherMap API**: Fetches weather data and validates locations. |
| 59 | + |
| 60 | +### Server |
| 61 | +- **Node.js**: Backend runtime environment. |
| 62 | +- **TypeScript**: Strongly typed programming language. |
| 63 | +- **Express.js**: Fast and lightweight web framework. |
| 64 | +- **Mongoose**: MongoDB Object Modeling for Node.js. |
| 65 | +- **MongoDB**: Database for storing user preferences and data. |
| 66 | +- **dotenv**: For environment variable management. |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## Getting Started |
| 71 | + |
| 72 | +### Prerequisites |
| 73 | + |
| 74 | +- [Node.js](https://nodejs.org/) (v14 or above) |
| 75 | +- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/) |
| 76 | +- A valid [OpenWeatherMap API Key](https://openweathermap.org/api) |
| 77 | +- A Telegram bot token from [BotFather](https://t.me/BotFather) |
| 78 | + |
| 79 | +### Installation |
| 80 | + |
| 81 | +1. Clone the repository: |
| 82 | + ```bash |
| 83 | + git clone https://github.com/deepsingh132/weatherbot.git |
| 84 | + cd weatherbot |
| 85 | + ``` |
| 86 | + |
| 87 | +2. Install dependencies: |
| 88 | + ```bash |
| 89 | + npm install |
| 90 | + ``` |
| 91 | + |
| 92 | +3. Set up environment variables: |
| 93 | + Create a `.env` file in the root directory (see [Environment Variables](#environment-variables)). |
| 94 | + |
| 95 | +4. Start the server and bot: |
| 96 | + ```bash |
| 97 | + npm run start |
| 98 | + ``` |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +## Environment Variables |
| 103 | + |
| 104 | +Set up the following keys in a `.env` file: |
| 105 | + |
| 106 | +```env |
| 107 | +PORT=3000 |
| 108 | +OPENWEATHER_API_KEY=your_openweathermap_api_key |
| 109 | +MONGO_URI=your_mongodb_connection_string |
| 110 | +BOT_TOKEN=your_telegram_bot_token |
| 111 | +``` |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## Bot Commands |
| 116 | + |
| 117 | +| Command | Description | Example | |
| 118 | +|---------------------|------------------------------------------|-----------------------------| |
| 119 | +| `/start` | Starts interaction with the bot. | `/start` | |
| 120 | +| `/current <city>` | Fetches current weather for a city. | `/current New York` | |
| 121 | +| `/subscribe` | Saves a preferred location. | `/subscribe` | |
| 122 | +| `/unsubscribe` | Removes a saved location | `/unsubscribe` | |
| 123 | +| `/update_city` | Configures location updates. | `/update_city` | |
| 124 | +| `/update_frequency` | Configures frequency updates. | `/update_frequency` | |
| 125 | +| `/help` | Displays help information. | `/help` | |
| 126 | +| `/about` | Provides information about the bot. | `/about` | |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## License |
| 131 | + |
| 132 | +This project is licensed under the GPL v3 License. See the [LICENSE](LICENSE) file for details. |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +## Author |
| 137 | + |
| 138 | +Developed with ❤️ by **Mandeep Singh** |
| 139 | +- [LinkedIn](https://linkedin.com/in/deepsingh132) |
| 140 | +- [GitHub](https://github.com/deepsingh132) |
| 141 | + |
| 142 | +--- |
0 commit comments