Flamengo Calendar Sync ⚽📅

Automated script that syncs Flamengo football matches to Google Calendar, including match results, goal scorers, and league standings.

Features

• 🗓️ Automatic Calendar Events: Creates events for all scheduled Flamengo matches
• ⚽ Match Results: Updates events with final scores after matches conclude
• 📊 Goal Details: Adds goal times and scorers to event notes
• 🟨 Card Information: Shows yellow and red cards in event notes (planned)
• 📈 League Standings: Shows position changes for league matches
• 📅 TBD Match Support: Creates all-day events for matches with unconfirmed times (planned)
• 🔔 Notifications: Alerts on errors (optional)
• 🔄 Auto-Sync: Works best when run on a schedule (e.g., every 15 minutes)

Supported Competitions

The script currently tracks Flamengo matches across all major competitions with the following prefixes:

• [BRA] - Campeonato Brasileiro Série A (Brasileirão)
• [CAR] - Campeonato Carioca
• [CDB] - Copa do Brasil
• [LIB] - Copa Libertadores da América
• [REC] - Recopa Sul-Americana
• [SUP] - Supercopa do Brasil
• [SUL] - Copa Sul-Americana
• [MUN] - Mundial de Clubes (Club World Cup)

Additional competitions can be added as needed.

Calendar Event Format

Scheduled Match

Title: [BRA] Flamengo x Vasco
Date: 15/01/2026 16:00 BRT
Location: Rua Prof. Eurico Rabelo, s/nº - Maracanã, Rio de Janeiro - RJ
Notes: 3ᵃ Rodada

After Match Ends

Title: [BRA] Flamengo (3) x (1) Vasco
Date: 15/01/2026 16:00 BRT
Location: Rua Prof. Eurico Rabelo, s/nº - Maracanã, Rio de Janeiro - RJ
Notes:
3ᵃ Rodada

Gols:
15' 1x0 Pedro
24' 1x1 João (Vasco)
45'+3' 2x1 De Arrascaeta
73' 3x1 Samuel Lino

Cartões:
23' 🟨 Pedro
67' 🟨 João (Vasco)
85' 🟥 Silva (Vasco)

Classificação:
3º (45 pts) → 2º (48 pts)

Note: Card information (yellow/red cards) will be added in a future update (Issue #23)

Prerequisites

• Node.js 18 or higher
• Google Cloud account (free)
• API-Football account (free tier: 100 requests/day)

Installation

1. Clone the Repository

# Clone the repository to your preferred location
git clone https://github.com/yourusername/flamengo-calendar-sync.git
cd flamengo-calendar-sync

# Install dependencies
npm install

2. Set Up Google Calendar API

1. Go to Google Cloud Console

2. Create a new project: "Flamengo Calendar Sync"

3. Enable the Google Calendar API

4. Create credentials:

   • Go to APIs & Services > Credentials
   • Click Create Credentials > Service Account
   • Name it "flamengo-sync-bot"
   • Click Create and Continue
   • Skip the optional steps

5. Download the service account JSON key:

   • Click on the newly created service account
   • Go to Keys tab
   • Click Add Key > Create new key
   • Choose JSON format
   • Download the file

6. Place the JSON file in your project directory:

   # Save as service-account.json in the project root
   flamengo-calendar-sync/service-account.json

7. Create a dedicated Google Calendar:

   • Go to Google Calendar
   • Click the + next to "Other calendars"
   • Select Create new calendar
   • Name: "Flamengo - Jogos"
   • Click Create calendar

8. Share calendar with service account:

   • Find your new calendar in the left sidebar
   • Click the three dots > Settings and sharing
   • Scroll to Share with specific people
   • Click Add people
   • Paste the service account email from the JSON file
   • Give it Make changes to events permission
   • Click Send

9. Get the Calendar ID:

   • In calendar settings, scroll to Integrate calendar
   • Copy the Calendar ID (looks like: xxx@group.calendar.google.com)

3. Set Up API-Football

1. Sign up at API-Football
2. Subscribe to the Free Plan (100 requests/day)
3. Get your API key from the dashboard

4. Configure Environment Variables

cd flamengo-calendar-sync
cp .env.example .env

Edit .env and update the following values:

• API_FOOTBALL_KEY: Your API-Football key
• GOOGLE_CALENDAR_ID: Your calendar ID from step 2.9
• GOOGLE_SERVICE_ACCOUNT_PATH: Path to service account JSON file (default: ./service-account.json)
• FLAMENGO_TEAM_ID: Will be discovered automatically (leave as 123 for now)

5. Test the Script

node src/index.js

Check the logs in logs/ directory and verify events appear in your Google Calendar.

6. Schedule the Script (Optional but Recommended)

For best results, run the script every 15 minutes. Here are examples for different operating systems:

Linux/macOS (cron):

# Edit crontab
crontab -e

# Add this line (replace /path/to with actual path)
*/15 * * * * cd /path/to/flamengo-calendar-sync && node src/index.js >> logs/cron-output.log 2>&1

Windows (Task Scheduler):

1. Open Task Scheduler
2. Create Basic Task: "Flamengo Calendar Sync"
3. Trigger: Daily, repeat every 15 minutes
4. Action: Start a program
   • Program: node
   • Arguments: src/index.js
   • Start in: C:\path\to\flamengo-calendar-sync

Docker (optional):

# Run as a scheduled container
docker run -d --name flamengo-sync \
  -v $(pwd):/app \
  -e TZ=America/Sao_Paulo \
  node:18-alpine \
  sh -c "cd /app && while true; do node src/index.js; sleep 900; done"

Project Structure

flamengo-calendar-sync/
├── src/
│   ├── api/
│   │   ├── apiFootball.js        # API-Football client
│   │   └── googleCalendar.js     # Google Calendar client
│   ├── services/
│   │   ├── matchProcessor.js     # Process match data
│   │   ├── eventBuilder.js       # Build calendar events
│   │   └── notificationService.js # Send notifications
│   ├── utils/
│   │   ├── logger.js             # Logging utilities
│   │   ├── retry.js              # Retry logic
│   │   └── timezone.js           # Timezone conversions
│   ├── config/
│   │   └── config.js             # Configuration
│   └── index.js                  # Main entry point
├── tests/                        # Test files
├── logs/                         # Log files (auto-generated)
├── .env                          # Environment variables (not in git)
├── .env.example                  # Environment template
├── .gitignore                    # Git ignore rules
├── package.json                  # Dependencies
├── README.md                     # This file
└── service-account.json          # Google credentials (not in git)

Monitoring

View Logs

# View today's log
tail -f logs/flamengo-sync-$(date +%Y-%m-%d).log

# View cron output (if using cron scheduling)
tail -f logs/cron-output.log

Check Last Execution

Logs show execution summary:

=================================
Flamengo Calendar Sync - Summary
=================================
Start time: 2026-01-11 14:30:00
End time: 2026-01-11 14:30:45

Scheduled Matches:
  - Fixtures found: 8
  - Events created: 3
  - Events skipped (existing): 5

Finished Matches:
  - Results found: 2
  - Events updated: 2

Errors: 0
Status: ✓ Success
=================================

Troubleshooting

Script not running on schedule

• Verify your scheduler configuration (cron, Task Scheduler, etc.)
• Check Node.js is in your system PATH
• Review scheduler logs for errors

"Cannot find module" errors

cd flamengo-calendar-sync
npm install

API errors

• Verify .env file has correct API keys
• Check API quota (100 requests/day for free tier)
• View API-Football dashboard for usage stats

Calendar events not created

• Verify service account has calendar access (step 2.8)
• Check GOOGLE_CALENDAR_ID is correct in .env
• Review logs for specific Google Calendar API errors

Rate limit errors

The free tier allows 100 requests/day. Running every 15 minutes = 96 requests/day, leaving 4 for retries. If you hit limits:

• Reduce execution frequency to every 20 minutes (72 requests/day)
• Or upgrade to a paid API-Football plan

API Usage Budget

Running every 15 minutes (96 times/day):

• Daily limit: 100 requests
• Per execution: ~1 request
• Strategy: Fetch both upcoming fixtures and recent results in a single API call
• Buffer: 4 requests reserved for retries

Project Development

This project is organized into milestones and issues on GitHub. You can track progress and see what features are planned:

Milestones

• v1.0 - Core Functionality: Basic script that fetches fixtures and creates calendar events
• v1.1 - Match Results & Updates: Update events with scores, goal details, cards, and standings
• v1.2 - Production Ready: Error handling, notifications, logging, and deployment guides
• v2.0 - Advanced Features: Enhanced features (match rescheduling, pre-match notifications, multi-team support, web dashboard)

Labels

All issues are tagged with appropriate labels for easy filtering:

• setup - Initial configuration and project setup
• api - API integration (API-Football, Google Calendar)
• calendar - Google Calendar specific work
• data-processing - Data transformation and business logic
• deployment - Deployment and scheduling
• documentation - Documentation and guides
• enhancement - Nice-to-have features
• bug - Bug fixes
• testing - Tests and quality assurance
• dependencies - Dependency updates

View all open issues to see what's being worked on or planned.

Contributing

This is a personal project, but suggestions and improvements are welcome! Please open an issue or submit a pull request.

License

MIT License - see LICENSE file for details.

Acknowledgments

• API-Football for providing football data
• Google Calendar API for calendar integration
• Flamengo supporters worldwide! 🔴⚫

---

Vamos Flamengo! 🔴⚫