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)

import os
from ggscore import Client

os.environ["GGSCORE_API_KEY"] = "your-key"  # or CS2_MATCH_API_KEY

with Client() as client:
    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

import asyncio
from ggscore import AsyncClient

async def main() -> None:
    async with AsyncClient() as client:
        print(await client.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

from ggscore import AuthenticationError, 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.