A Python tool that syncs your RetroAchievements "Want to Play" list with completion time data from both HowLongToBeat and RetroAchievements player statistics.
Plan your retro gaming backlog with accurate time estimates for both casual playthroughs and full mastery.
Note: This is rate limited to not overload RA or HLTB servers
This tool pulls timing data from two sources:
| Source | Data | What it measures |
|---|---|---|
| RetroAchievements | RA_Beat, RA_Master | Actual median times from RA players earning achievements |
| HowLongToBeat | HLTB_Beat, HLTB_Complete | General playthrough times (not achievement-focused) |
RA Mastery times are authoritative - they come from actual player data and reflect how long it takes to earn all achievements, including challenge runs, collectibles, and multiple playthroughs.
HLTB times are useful as a baseline comparison but typically underestimate mastery time by 2-5x depending on the achievement set difficulty.
- Pulls your Want to Play list directly from the RetroAchievements API
- Fetches actual RA mastery times from player statistics (API_GetGameProgression)
- Fetches beat and completionist times from HowLongToBeat for comparison
- Efficiency metric (points per hour) to prioritize your backlog
- Smart title matching for better HLTB results
- GUI login dialog with secure credential storage
- Progress caching (safe to interrupt and resume)
- Exports to Excel with all data and match notes
The HLTB search uses intelligent matching to handle RetroAchievements naming conventions:
- Pokemon handling: Normalizes
étoe, strips "Version" suffix - Alternate titles: Searches both sides of pipe separators (e.g.,
HeartGold | SoulSilver) - Sequel detection: Penalizes numbered sequels when searching for the original (prevents
AladdinmatchingAladdin III) - Title cleanup: Removes
~Hack~,[Subset], region codes(USA), version info(Rev 1), etc. - Special characters: Normalizes
ōtoo(Okami),ütou, and other diacritics
- Python 3.10 or higher
- A RetroAchievements account with a Want to Play list
- Your RA API key (get it from retroachievements.org/settings)
pip install howlongtobeatpy pandas openpyxl aiohttp keyringNote: keyring is optional but recommended for secure credential storage. Without it, credentials are stored in a local file.
python ra_backlog_timer.pyOn first run, a login dialog will appear asking for your RetroAchievements username and API key. These are saved securely for future runs.
# Specify output file
python ra_backlog_timer.py -o MyBacklog.xlsx
# Re-fetch your Want to Play list from RetroAchievements
python ra_backlog_timer.py --refresh
# Clear stored credentials and enter new ones
python ra_backlog_timer.py --reset-creds======================================================================
RetroAchievements + HowLongToBeat Scraper
======================================================================
Fetching Want to Play list for 'USER' from RetroAchievements...
Fetched 345/345 games...
Total: 345 games in Want to Play list
Processing 345 games...
Complete!
Total games: 345
From cache: 0
Fetched: 345
Skipped (already had data): 0
Games with HLTB data: 338
Games with RA mastery data: 334
HLTB Match quality:
Exact matches: 299
Fuzzy matches: 11
Loose matches: 2
Poor matches (needs review): 21
No match found: 5
RA vs HLTB Comparison (323 games with both):
Avg HLTB Completionist: 48.7 hours
Avg RA Mastery: 42.9 hours
RA takes 0.9x longer on average
RA Mastery Time estimates:
Total Mastery time: 14393.9 hours (599.7 days)
Average Mastery: 43.1 hours
Games by system:
PlayStation 2: 83
PlayStation: 53
SNES/Super Famicom: 45
PlayStation Portable: 26
Game Boy Advance: 24
Nintendo 64: 23
Nintendo DS: 23
Genesis/Mega Drive: 21
NES/Famicom: 17
GameCube: 14
Most Efficient Games (highest points per hour of mastery):
135.2 pts/hr - Golden Axe (284 pts, 2.1h RA)
115.6 pts/hr - Mighty Morphin Power Rangers: The Movie (416 pts, 3.6h RA)
92.3 pts/hr - Alien Soldier (323 pts, 3.5h RA)
88.3 pts/hr - Altered Beast (318 pts, 3.6h RA)
85.7 pts/hr - The Adventures of Batman & Robin (240 pts, 2.8h RA)
80.9 pts/hr - Castlevania: The Adventure (445 pts, 5.5h RA)
77.9 pts/hr - Streets of Rage (740 pts, 9.5h RA)
75.6 pts/hr - Aladdin (295 pts, 3.9h RA)
69.0 pts/hr - Streets of Rage 2 (331 pts, 4.8h RA)
66.7 pts/hr - Alien 3 (360 pts, 5.4h RA)
Results saved to: HowLongToBeat.xlsx
Games without any time data (1):
- SaGa Frontier II
The tool creates an Excel file with the following columns:
| Column | Description |
|---|---|
| Title | Game title from RetroAchievements |
| System | Console/platform |
| Achievements | Number of achievements available |
| Points | Total achievement points |
| RA_ID | RetroAchievements game ID |
| HLTB_Beat | HowLongToBeat main story time (hours) |
| HLTB_Complete | HowLongToBeat completionist time (hours) |
| RA_Beat | RetroAchievements median time to beat (hours) |
| RA_Master | RetroAchievements median time to master (hours) |
| RA_Players | Number of distinct players on RetroAchievements |
| Points_Per_Hour | Efficiency metric (Points / RA_Master time) |
| Comments | HLTB match quality notes |
The Points_Per_Hour column helps you prioritize your backlog by showing which games give you the most RetroAchievements points for your time investment.
Higher values = more "rewarding" games
This is calculated using RA_Master time when available (actual player data), falling back to HLTB_Complete if RA data is missing.
Sort by this column descending to find quick wins that will boost your RA rank efficiently.
The Comments column indicates how well the game matched on HowLongToBeat:
| Comment | Meaning |
|---|---|
| (empty) | Exact title match |
Fuzzy match: [name] |
High confidence match with minor differences |
Loose match (X%): [name] |
Moderate confidence, worth verifying |
Poor match (X%): [name] - VERIFY |
Low confidence, needs manual review |
No HLTB match found |
Game not found in HowLongToBeat database |
The tool creates several cache files in the working directory:
HowLongToBeat.xlsx- Your output file (or custom name via -o)ra_wanttoplay_cache.json- Cached Want to Play list from RAhltb_progress.json- Lookup progress cache (for resuming).ra_credentials.json- Credentials file (only if keyring unavailable)
To re-run HLTB matching (e.g., after a matching algorithm update):
rm hltb_progress.json
python ra_backlog_timer.pyTo refresh your Want to Play list from RetroAchievements:
python ra_backlog_timer.py --refreshYour RetroAchievements API key is sensitive and should be protected.
With keyring installed (recommended):
- Credentials are stored in your operating system's secure credential storage
- Windows: Credential Manager
- macOS: Keychain
- Linux: Secret Service (GNOME Keyring or KWallet)
Without keyring:
- Credentials are stored in
.ra_credentials.jsonin the working directory - File permissions are set to 600 (owner read/write only) on Unix systems
- Never commit your API key to version control
- The
.ra_credentials.jsonfile is a hidden file but is NOT encrypted - If you suspect your API key is compromised, regenerate it at retroachievements.org/settings
This tool makes HTTPS requests to:
retroachievements.org- to fetch your Want to Play list and game progression datahowlongtobeat.com- to fetch game completion times
No data is sent to any other servers.
- Verify your API key at retroachievements.org/settings
- Run with
--reset-credsto re-enter your credentials - Make sure you can access your own Want to Play list (must be your account or mutual followers)
- Add some games to your Want to Play list on RetroAchievements
- Check that you are querying your own username
- Make sure you have tkinter installed (included with most Python distributions)
- On Linux, you may need:
sudo apt install python3-tk
- The dialog should auto-scale on Windows 10/11
- If text appears too small, try running from a terminal with DPI awareness enabled
- Not all games have enough player data for median times
- Newer or less popular games may not have mastery statistics yet
- The tool will still show HLTB times as a fallback
- Delete
hltb_progress.jsonand re-run to get fresh matches - Check the Comments column for match quality indicators
- Some games (especially romhacks, subsets, or regional variants) may not exist on HLTB
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
- RetroAchievements for the amazing retro gaming community and API
- HowLongToBeat for game completion time data
- howlongtobeatpy for the Python HLTB library