Client

The main entry point for interacting with the Liquipedia API.

A LiquipediaClient instance owns a single httpx session and exposes one resource attribute per LPDB v3 data type (e.g. client.players, client.matches). See Resources for the full list and per-resource details.

Use the client as a context manager — the with block guarantees the HTTP session is closed on exit, including when exceptions propagate.

class liquipydia.LiquipediaClient

Bases: object

Synchronous client for the Liquipedia API v3.

Parameters:

  • app_name (str) – Application name used in the User-Agent header.

  • api_key (str | None (default: None)) – API key for authentication. Falls back to the LIQUIPEDIA_API_KEY environment variable.

  • timeout (float (default: 30.0)) – Request timeout in seconds.

  • max_retries (int (default: 3)) – Maximum number of retries on HTTP 429 responses.

  • retry_backoff_factor (float (default: 1.0)) – Base factor for exponential backoff on retries.

Examples

>>> with LiquipediaClient("my-app", api_key="secret") as client:
...     response = client.players.list("dota2")
__init__(app_name, api_key=None, *, timeout=30.0, max_retries=3, retry_backoff_factor=1.0)
broadcasters: BroadcastersResource
companies: CompaniesResource
datapoints: DatapointsResource
matches: MatchResource
placements: PlacementsResource
players: PlayersResource
series: SeriesResource
squad_players: SquadPlayersResource
standings_entries: StandingsEntriesResource
standings_tables: StandingsTablesResource
teams: TeamsResource
tournaments: TournamentsResource
transfers: TransfersResource
team_templates: TeamTemplateResource
team_template_list: TeamTemplateListResource
close()

Close the underlying HTTP session.

Return type:

None

get(endpoint, params)

Send a GET request to the API and return the parsed response.

Parameters:

  • endpoint (str) – API path segment (e.g. "player").

  • params (dict[str, Any]) – Query parameters to include in the request.

Return type:

ApiResponse

Returns:

Parsed API response.

Raises:

  • AuthError – If the API key is invalid or missing (HTTP 403).

  • NotFoundError – If the requested data does not exist (HTTP 404).

  • RateLimitError – If retries are exhausted after HTTP 429 responses.

  • ApiError – If the API returns an error in the response body.

  • LiquipediaError – For other unexpected HTTP errors.

paginate(endpoint, params, *, page_size=20, max_results=None)

Iterate through paginated API results.

Yields individual record dicts, automatically requesting successive pages. Stops when a page returns fewer records than page_size or when max_results records have been yielded.

Parameters:

  • endpoint (str) – API path segment (e.g. "player").

  • params (dict[str, Any]) – Base query parameters (limit and offset are managed internally).

  • page_size (int (default: 20)) – Number of records per page (max 1000).

  • max_results (int | None (default: None)) – Stop after yielding this many records. None for unlimited.

Yields:

Individual record dicts from the API.

Direct HTTP access

The methods below are public and resource classes call them internally. You only need them when hitting an endpoint that the resource layer does not yet model, or when implementing your own Resource subclass.

LiquipediaClient.get(endpoint, params)

Send a GET request to the API and return the parsed response.

Parameters:

  • endpoint (str) – API path segment (e.g. "player").

  • params (dict[str, Any]) – Query parameters to include in the request.

Return type:

ApiResponse

Returns:

Parsed API response.

Raises:

  • AuthError – If the API key is invalid or missing (HTTP 403).

  • NotFoundError – If the requested data does not exist (HTTP 404).

  • RateLimitError – If retries are exhausted after HTTP 429 responses.

  • ApiError – If the API returns an error in the response body.

  • LiquipediaError – For other unexpected HTTP errors.

LiquipediaClient.paginate(endpoint, params, *, page_size=20, max_results=None)

Iterate through paginated API results.

Yields individual record dicts, automatically requesting successive pages. Stops when a page returns fewer records than page_size or when max_results records have been yielded.

Parameters:

  • endpoint (str) – API path segment (e.g. "player").

  • params (dict[str, Any]) – Base query parameters (limit and offset are managed internally).

  • page_size (int (default: 20)) – Number of records per page (max 1000).

  • max_results (int | None (default: None)) – Stop after yielding this many records. None for unlimited.

Yields:

Individual record dicts from the API.