{"id":29804327,"url":"https://github.com/l1ve4code/icbc-road-test-catcher","last_synced_at":"2025-07-28T12:45:12.154Z","repository":{"id":299160232,"uuid":"1002224819","full_name":"l1ve4code/icbc-road-test-catcher","owner":"l1ve4code","description":"An automated Python script that monitors and books available road test appointments at ICBC (Insurance Corporation of British Columbia) locations in Canada.","archived":false,"fork":false,"pushed_at":"2025-06-15T02:24:17.000Z","size":13,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-15T03:28:57.516Z","etag":null,"topics":["automation","docker-compose","icbc-road-test","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/l1ve4code.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,"zenodo":null}},"created_at":"2025-06-15T01:49:06.000Z","updated_at":"2025-06-15T03:04:44.000Z","dependencies_parsed_at":"2025-06-15T03:39:14.536Z","dependency_job_id":null,"html_url":"https://github.com/l1ve4code/icbc-road-test-catcher","commit_stats":null,"previous_names":["l1ve4code/icbc-road-test-catcher"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/l1ve4code/icbc-road-test-catcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1ve4code%2Ficbc-road-test-catcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1ve4code%2Ficbc-road-test-catcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1ve4code%2Ficbc-road-test-catcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1ve4code%2Ficbc-road-test-catcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/l1ve4code","download_url":"https://codeload.github.com/l1ve4code/icbc-road-test-catcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/l1ve4code%2Ficbc-road-test-catcher/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267520152,"owners_count":24100817,"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","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["automation","docker-compose","icbc-road-test","python"],"created_at":"2025-07-28T12:45:10.751Z","updated_at":"2025-07-28T12:45:12.042Z","avatar_url":"https://github.com/l1ve4code.png","language":"Python","readme":"# ICBC Road Test Catcher\n\nAn automated Python script that monitors and books available road test appointments at ICBC (Insurance Corporation of British Columbia) locations in Canada.\n\n## Problem Statement\n\nRoad test appointments in British Columbia are typically booked solid for 6+ months in advance, making it extremely difficult to find earlier available slots. This script continuously monitors the ICBC booking system and automatically secures the earliest available appointment within your preferred date range.\n\n## Features\n\n- **Automated Monitoring**: Continuously checks for available appointments every 90 seconds\n- **Smart Filtering**: Only considers appointments within your specified date range\n- **Full Automation**: Complete booking process without manual intervention\n- **Email Integration**: Automatically retrieves and processes OTP codes from Gmail\n- **Token Management**: Handles authentication token refresh automatically\n- **Multi-location Support**: Can monitor multiple ICBC locations simultaneously\n- **Error Handling**: Robust error handling with retry mechanisms\n- **Docker Support**: Easy deployment with Docker Compose for consistent environment\n- **Timezone Aware**: Properly configured for Pacific Time (America/Vancouver)\n\n## How It Works\n\n1. **Authentication**: Logs into ICBC system using your credentials\n2. **Monitoring**: Continuously scans for available appointments\n3. **Booking Process**: When a suitable slot is found:\n   - Locks the appointment temporarily\n   - Requests OTP code via email\n   - Automatically retrieves OTP from Gmail\n   - Verifies the OTP code\n   - Completes the booking\n\n## Prerequisites\n\n### For Docker Installation (Recommended)\n- Docker and Docker Compose installed\n- Gmail account with App Password enabled\n- Valid ICBC learner's license and credentials\n\n### For Local Python Installation\n- Python 3.7+\n- Gmail account with App Password enabled\n- Valid ICBC learner's license and credentials\n\n## Installation\n\n### Option 1: Docker (Recommended)\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/l1ve4code/icbc-road-test-catcher.git\ncd icbc-road-test-catcher\n```\n\n2. Configure your credentials in `docker-compose.yml` (see Configuration section below)\n\n3. Run with Docker Compose:\n```bash\ndocker-compose up -d\n```\n\n### Option 2: Local Python Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/l1ve4code/icbc-road-test-catcher.git\ncd icbc-road-test-catcher\n```\n\n2. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n## Configuration\n\n### Docker Configuration (Recommended)\n\nEdit the `docker-compose.yml` file and replace the placeholder values with your personal information:\n\n```yaml\nenvironment:\n  - TZ=America/Vancouver\n  - USER_LAST_NAME=YourLastName          # Replace with your last name\n  - USER_LICENSE_NUMBER=1234567          # Replace with your license number\n  - USER_KEYWORD=your_keyword_here       # Replace with your ICBC keyword\n  - USER_GMAIL=your.email@gmail.com      # Replace with your Gmail address\n  - USER_GMAIL_APP_PASSWORD=your_16_character_app_password  # Replace with Gmail App Password\n  - DESIRED_DATE_START=2025-06-24        # Replace with your preferred start date (YYYY-MM-DD)\n  - DESIRED_DATE_END=2025-06-30          # Replace with your preferred end date (YYYY-MM-DD)\n```\n\n### Local Python Configuration\n\nEdit the `CONFIG` dictionary in `main.py` with your personal information, or set environment variables:\n\n```bash\nexport USER_LAST_NAME=\"YourLastName\"\nexport USER_LICENSE_NUMBER=\"1234567\"\nexport USER_KEYWORD=\"your_keyword_here\"\nexport USER_GMAIL=\"your.email@gmail.com\"\nexport USER_GMAIL_APP_PASSWORD=\"your_16_character_app_password\"\nexport DESIRED_DATE_START=\"2025-06-24\"\nexport DESIRED_DATE_END=\"2025-06-30\"\n```\n\n**Note**: You must enable 2-factor authentication on Gmail and generate an App Password. Regular Gmail passwords won't work.\n\n### Date Range\n\nThe desired date range is now configured via environment variables:\n- `DESIRED_DATE_START`: Start date in YYYY-MM-DD format (default: 2025-06-24)\n- `DESIRED_DATE_END`: End date in YYYY-MM-DD format (default: 2025-06-30)\n\n### Location IDs\n```python\n\"location_ids\": [214]  # 214 = Duncan, add more IDs for other locations\n```\n\n### Other Settings\n```python\n\"check_interval\": 90,           # Seconds between appointment checks\n\"token_refresh_interval\": 1500  # Seconds between token refreshes (25 minutes)\n```\n\n## Gmail App Password Setup\n\n1. Enable 2-Factor Authentication on your Google account\n2. Go to Google Account settings → Security → App passwords\n3. Generate a new app password for \"Mail\"\n4. Use this 16-character password in the configuration\n\n## Usage\n\n### Docker Usage (Recommended)\n\n1. Start the container:\n```bash\ndocker-compose up -d\n```\n\n2. View logs:\n```bash\ndocker-compose logs -f icbc-catcher\n```\n\n3. Stop the container:\n```bash\ndocker-compose down\n```\n\n### Local Python Usage\n\nRun the script:\n```bash\npython main.py\n```\n\n### What the script does:\n- Start monitoring immediately\n- Display status updates in the console\n- Automatically book when a suitable appointment is found\n- Stop execution after successful booking\n\n## Sample Output\n\n```\nToken refreshed. drvrID: 12345678\nScript started. Beginning monitoring for available dates...\nFound 3 available dates for location 214\nFound early date: 2025-06-25\nDate 2025-06-25 successfully locked\nOTP code sent to email\nOTP code successfully verified\nBooking completed successfully!\nBooking completed successfully! Script terminating.\n```\n\n## Location IDs\n\nCommon ICBC locations and their IDs:\n- Duncan: 214\n- Victoria: (add ID if known)\n- Vancouver: (add ID if known)\n\nTo find other location IDs, inspect network traffic in your browser when selecting different locations on the ICBC website.\n\n## Important Notes\n\n- **Rate Limiting**: The script respects ICBC's servers with reasonable intervals\n- **Legal Compliance**: This tool automates the same process you would do manually\n- **Single Use**: Script stops after successfully booking one appointment\n- **Timezone**: Configured for Pacific Time (America/Vancouver)\n\n## Troubleshooting\n\n### Docker Commands\n\n```bash\n# View container logs\ndocker-compose logs -f icbc-catcher\n\n# Restart the container\ndocker-compose restart icbc-catcher\n\n# Rebuild the container (after code changes)\ndocker-compose up --build -d\n\n# Access container shell for debugging\ndocker-compose exec icbc-catcher /bin/bash\n\n# Remove container and volumes\ndocker-compose down -v\n```\n\n### Common Issues\n\n1. **Authentication Failed**\n   - Verify your ICBC credentials are correct\n   - Check that your license is valid and active\n\n2. **Gmail Connection Issues**\n   - Ensure 2FA is enabled on Gmail\n   - Verify App Password is correctly generated and entered\n   - Check IMAP is enabled in Gmail settings\n\n3. **No Appointments Found**\n   - Adjust your date range\n   - Add more location IDs\n   - Check if appointments are available manually on ICBC website\n\n4. **Token Refresh Errors**\n   - Usually resolves automatically on next refresh cycle\n   - Restart script if persistent\n\n5. **Docker Issues**\n   - Ensure Docker and Docker Compose are installed\n   - Check container logs: `docker-compose logs icbc-catcher`\n   - Verify timezone is set correctly in container\n\n## Disclaimer\n\nThis tool is for educational purposes and personal use only. Users are responsible for:\n- Complying with ICBC terms of service\n- Using the tool responsibly and ethically\n- Not overloading ICBC servers\n\n## Author\n\n**Telegram:** [@live4code](https://t.me/live4code)  \n**Email:** steven.marelly@gmail.com\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fl1ve4code%2Ficbc-road-test-catcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fl1ve4code%2Ficbc-road-test-catcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fl1ve4code%2Ficbc-road-test-catcher/lists"}