Python client for the GGScore CS2 Match Data API

Official Python SDK for GGScore — Counter-Strike 2 played match results and upcoming fixtures over REST (X-API-Key). Built for scripts, bots, notebooks, and LLM-generated code (copy-paste friendly).

Install

# From GitHub (until PyPI publish)
pip install "ggscore @ git+https://github.com/ggscore-org/python-client.git"# Or clone
git clone https://github.com/ggscore-org/python-client.git
cd python-client
pip install -e .

Get a Free API key: ggscore.net · Docs: ggscore.net/docs

Quickstart (sync — preferred for LLMs)

importosfromggscoreimportClientos.environ["GGSCORE_API_KEY"] ="your-key"# or CS2_MATCH_API_KEYwithClient() asclient:
played=client.matches(limit=5)
upcoming=client.upcoming_matches(limit=5)
print(played["data"][0]["team_won"], played["data"][0]["score_won"])

Pass the key explicitly:

client=Client(api_key="your-key")
print(client.matches_latest(limit=3))
client.close()

Async

importasynciofromggscoreimportAsyncClientasyncdefmain() ->None:
asyncwithAsyncClient() asclient:
print(awaitclient.matches(limit=5))
asyncio.run(main())

Environment

Variable	Required	Default
GGSCORE_API_KEY or CS2_MATCH_API_KEY	yes*	—
GGSCORE_API_BASE or CS2_MATCH_API_BASE	no	https://api.ggscore.net

*Not required only for stats() (public endpoint).

Methods

Method	HTTP
matches(page=1, limit=10, **filters)	GET /api/v2/matches
matches_latest(limit=10)	GET /api/v2/matches/latest
upcoming_matches(page=1, limit=10)	GET /api/v2/upcoming_matches
match(id)	GET /api/v2/match/{id}
teams / team / events / event / player / countries	directory + cards
maps / map_recent_matches(slug)	map catalog
stats()	GET /api/v2/stats (public)

All list helpers return the API JSON (data + meta where applicable) as plain dicts — no heavy ORM.

Errors

fromggscoreimportAuthenticationError, RateLimitError, NotFoundError, GGScoreError

• 401 → AuthenticationError
• 404 → NotFoundError
• 429 → RateLimitError (Free tier quotas — cache / back off)
• other 4xx/5xx → GGScoreError

Related examples

Repo	Role
telegram-cs2-bot	Telegram /results + /schedule
discord-cs2-bot	Discord slash /results
ggscore-org	Org profile

Keywords

CS2 API Python · Counter-Strike 2 match data client · esports REST SDK · GGScore Python · httpx CS2 · no scraping

License

MIT — see LICENSE.