USCF Chess Tournament Scraper

Scrapes a US Chess Federation member's full tournament history, game-level results, and computes win-rate statistics by opponent rating bracket.

Features

• Modern API (primary): Fetches structured JSON from ratings-api.uschess.org — no HTML parsing needed
• Legacy fallback: Falls back to USCF MSA + chessevents.com scraping when the API is unavailable
• Player name search: Look up by name if USCF ID is unknown
• All rating systems: Regular, Quick, Blitz, Online (R, Q, B, OR, OQ, OB)
• Configurable brackets: Set your own rating bucket width (default 100 points)
• Forfeit tracking: Records B/U/H/F/X results separately
• Rich per-bracket stats: Win%, draw%, loss%, scoring%, points, average opponent rating
• Anti-detection: Playwright stealth mode for legacy browser fallback
• Rate limit handling: Exponential backoff with opponent rating caching

How it works

1. Modern path: Calls ratings-api.uschess.org/api/v1/ REST API for player info, events, and games — returns clean JSON, no browser required
2. Legacy fallback: If the API fails, scrapes USCF MSA for tournament history and chessevents.com for crosstables (with Playwright for JS-rendered pages)
3. Stats engine: Aggregates games into configurable rating brackets with win/draw/loss rates, points, and average opponent rating

Input

Field	Type	Required	Default	Description
uscfId	string	No	—	8-digit USCF member ID (required if playerName is not set)
playerName	string	No	—	Player name for search, e.g. "Manuel, Iqraa"
bracketSize	integer	No	100	Width of opponent rating buckets for stats
includeQuick	boolean	No	false	Include quick-rated (G/15–G/30) games
includeBlitz	boolean	No	false	Include blitz-rated games
includeOnline	boolean	No	false	Include online-rated games (Chess.com)
maxTournaments	integer	No	0	Maximum tournaments to process (0 = all)
useModernApi	boolean	No	true	Use modern ratings API as primary source
usePlaywright	boolean	No	true	Use Playwright fallback for legacy mode

Example

Input

{
  "uscfId": "30665747",
  "bracketSize": 100,
  "maxTournaments": 5
}

Output

1. Player info

{
  "type": "player",
  "uscfId": "30665747",
  "name": "Iqraa Manuel",
  "state": "VA",
  "expiration": "2026-12-31",
  "fideId": "39971732",
  "ratings": {
    "regular": { "rating": 1872, "provisional": false },
    "quick": { "rating": 1350, "provisional": true, "gamesPlayed": 21 }
  }
}

2. Tournament

{
  "type": "tournament",
  "id": "202607050483",
  "name": "54th Annual World Open",
  "startDate": "2026-07-01",
  "endDate": "2026-07-05",
  "stateCode": "DC",
  "gamesCount": 9
}

3. Game

{
  "type": "game",
  "result": "loss",
  "color": "white",
  "opponent": { "name": "Alan Stolyarov", "uscfId": "14490864", "rating": 1979 },
  "eventName": "54th Annual World Open",
  "ratingSystem": "R"
}

4. Summary

{
  "type": "summary",
  "source": "modern-api",
  "playerName": "Iqraa Manuel",
  "totalGames": 243,
  "wins": 138,
  "draws": 60,
  "losses": 45,
  "forfeits": 0,
  "winPercent": 56.8,
  "drawPercent": 24.7,
  "lossPercent": 18.5,
  "scoringPercent": 69.1,
  "averageOpponentRating": 1678,
   "byRatingRange": {
     "0-100":    { "games": 0, "wins": 0, "draws": 0, "losses": 0, "winPercent": 0, "scoringPercent": 0, "points": 0, "averageOpponentRating": null },
     ...
     "1600-1700": { "games": 13, "wins": 9, "draws": 2, "losses": 2, "winPercent": 69.2, "scoringPercent": 76.9, "points": 10, "averageOpponentRating": 1660 },
     ...
     "2900-3000": { "games": 0, "wins": 0, "draws": 0, "losses": 0, "winPercent": 0, "scoringPercent": 0, "points": 0, "averageOpponentRating": null }
   }
}

API endpoints used (modern path)

Endpoint	Purpose
GET /api/v1/members/{id}	Player profile and ratings
GET /api/v1/members/{id}/events	Tournament history
GET /api/v1/members/{id}/games?eventId=X	Game-level results per event

Use cases

• Coaches: Track student progress across tournaments
• Players: Get a complete picture of your career statistics
• Analysts: Study performance patterns by opponent rating range
• Parents: Monitor junior player development

Deployment

Local development

pip install -r requirements.txt
python -m src.main

Apify

$apify push