Singapore Carpark Availability Bot 🚗

A Telegram bot that helps users find nearby carparks in Singapore and check their real-time availability.

Features

• 🔍 Search for carparks near any location in Singapore
• 📊 View real-time availability of parking lots
• 📍 Shows distance to each carpark from your specified location
• 🚦 Visual indicators of carpark occupancy (🟢 Available, 🟡 Moderate, 🟠 Busy, 🔴 Very Busy)

Prerequisites

• Python 3.8+
• Telegram Bot Token (obtained from @BotFather)
• Google Maps Geocoding API key
• Internet connection to access the Google Maps API and Data.gov.sg API

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/singapore-carpark-bot.git
   cd singapore-carpark-bot

2. Create a virtual environment and activate it:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the required packages:

   pip install -r requirements.txt

4. Create a .env file in the root directory with your API keys:

   TELEGRAM_TOKEN=your_telegram_bot_token_here
   API_KEY=your_google_api_key_here
   

Getting the Carpark Dataset

The bot requires the HDB Carpark Information dataset to function properly. Follow these steps to download it:

1. Visit the HDB Carpark Information dataset on data.gov.sg (dataset ID: d_23f946fa557947f93a8043bbef41dd09)

2. Download the CSV file by clicking on "Download" button

3. Place the downloaded CSV file in the root directory of the project and rename it to HDBCarparkInformation.csv

4. Generate the carpark locations database by running:

   python gen_carparks.py

This will create a carpark_locations.json file that contains all carpark locations with their coordinates.

Usage

1. Start the bot:

   python bot.py

2. Open Telegram and search for your bot

3. Start a conversation with /start

4. Send a location in Singapore (address, postal code, landmark) to find nearby carparks

How It Works

1. User sends a location to the bot
2. The bot uses Google Maps Geocoding API to convert the location to coordinates
3. The bot finds nearby carparks within a 1km radius
4. The bot fetches real-time availability data from data.gov.sg API
5. Results are formatted and sent back to the user

Project Structure

├── bot.py                  # Main bot implementation
├── gen_carparks.py         # Script to generate carpark database
├── carpark_locations.json  # Generated database of carpark locations
├── converter.py            # SVY21 to WGS84 coordinate converter
├── google_geocode.py       # Google Maps Geocoding API integration
├── .env                    # Environment variables (including bot token and API key)
├── scraper/
│   ├── __init__.py
│   ├── Carpark_grabber.py  # Scraper for carpark availability data
│   ├── parser.py           # Content parsers (HTML, JSON, XML)
│   ├── requester.py        # HTTP request handler
│   └── scraper.py          # Base scraper class

API Endpoints Used

• Carpark Availability API: https://api.data.gov.sg/v1/transport/carpark-availability
• Google Maps Geocoding API: https://maps.googleapis.com/maps/api/geocode/json

Requirements

• python-telegram-bot
• requests
• pandas
• python-dotenv
• beautifulsoup4

Data Acknowledgement

This project uses the HDB Carpark Information dataset (ID: d_23f946fa557947f93a8043bbef41dd09) from data.gov.sg, which is made available under the Singapore Open Data License.

Data is provided by the Housing & Development Board (HDB) and accessed through the data.gov.sg API.

The SVY21 to WGS84 coordinate conversion functionality is based on cgcai/SVY21.

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request