HK Volunteer Work Search

A Flask-based web application that searches for volunteer work in Hong Kong, filtered by date. It aggregates data from four different websites:

1. 社職 (Social Career): https://www.socialcareer.org/
2. AVS (Agency for Volunteer Service): https://www.avs.org.hk/
3. HandsOn Hong Kong: https://handsonhongkong.org/zh/
4. Time Auction: https://timeauction.org/en

Prerequisites

• Python 3.9+: Make sure you have Python 3.9 or a later version installed. You can check your Python version by running python --version or python3 --version in your terminal. If you don't have it, download it from python.org.
• pip: pip is the package installer for Python. It usually comes bundled with Python installations. You can check if you have it by running pip --version or pip3 --version. If not install by python -m ensurepip --upgrade

Installation and Setup

1. Clone the Repository (or Download):

   • Using Git (Recommended): Open your terminal or command prompt and run:

     git clone https://github.com/dylanpong1109/vol_work

   • Downloading as a ZIP: If you don't have Git, go to the GitHub repository page and click the "Code" button, then select "Download ZIP". Extract the downloaded ZIP file to a folder of your choice. Open a terminal or command prompt and navigate to that folder using the cd command.

2. Install Dependencies:

   The project's dependencies are listed in the requirements.txt file. Install them using pip:

   pip install -r requirements.txt

   Or if you have both python2 and python3 installed

   pip3 install -r requirements.txt

   This command installs Flask and other necessary libraries.

3. Fetch Data:

   Before running the application for the first time (and periodically to update the data), you need to fetch the volunteer event data from the four websites. Run the provided script:

   python fetch_data.py

   Or

   python3 fetch_data.py

   This script will create (or update) the following JSON files in the same directory as the script:

   • response.json (Social Career data)
   • response_avs.json (AVS data)
   • response_handson.json (HandsOn Hong Kong data)
   • response_time_auction.json (Time Auction data)

   Important: This step might take a while, depending on your internet connection and the responsiveness of the target websites. The script scrapes data, so it's subject to changes in the websites' structure. If the script fails, you might need to update the scraping logic in fetch_data.py.

Running the Application

1. Start the Flask Server:

   Once you've fetched the data, you can start the Flask development server:

   python app.py

   Or

   python3 app.py

   You should see output similar to this:

    * Serving Flask app 'app'
    * Debug mode: on
    * Running on http://127.0.0.1:5000
    * Restarting with stat
    * Debugger is active!
    * Debugger PIN: xxx-xxx-xxx
   

2. Access the Web Interface:

   Open your web browser and go to http://127.0.0.1:5000/. You should see the web interface with a date input field.

3. Search for Events:

   • Enter a date in the "Start Date" field (YYYY-MM-DD format).
   • Click the "Search" button.
   • The page will display a list of volunteer opportunities matching the selected date, aggregated from the four websites. The results are sorted by start time.

Troubleshooting

• ModuleNotFoundError: No module named 'flask' (or similar errors): This means the required libraries weren't installed correctly. Double-check that you ran pip install -r requirements.txt in the correct directory (the project's root directory). You might need to use pip3 instead of pip.
• fetch_data.py fails: The websites being scraped might have changed their structure. You'll need to inspect the website's HTML and update the scraping logic in fetch_data.py accordingly. This requires some knowledge of web scraping techniques (using libraries like requests and BeautifulSoup).
• No results are displayed:
  • Make sure you've run fetch_data.py to populate the JSON data files.
  • Try a different date. There might not be any events listed for the date you selected.
  • Check the terminal output for any error messages from the Flask server.

Important Notes

• Web Scraping: This project relies on web scraping, which can be fragile. If the target websites change their HTML structure, the fetch_data.py script will likely need to be updated.
• Rate Limiting: Be mindful of how frequently you run fetch_data.py. Scraping websites too often may lead to your IP address being blocked.
• Data Accuracy: The accuracy of the displayed information depends on the data provided by the source websites.
• Development Server: The Flask development server (app.run(debug=True)) is not suitable for production use. For deployment, you should use a production-ready WSGI server like Gunicorn or uWSGI.