Python PyPI Python 3.9+

Python SDK

Official Python client built on httpx. Typed errors, context manager support, and automatic batch chunking.

install pip

$ pip install tcglookup

Key Features

Python 3.9+

Works on Python 3.9, 3.10, 3.11, 3.12 and beyond.

Built on httpx

Sync and async support via httpx. Drop into any project.

Typed Errors

AuthenticationError, PlanAccessError, NotFoundError, RateLimitError.

Context Manager

Use with-statement to manage connection lifecycle cleanly.

Auto-chunk Batches

Pass any number of IDs — SDK splits into ≤20-ID chunks automatically.

Full Type Hints

Fully annotated — works great with mypy and pyright.

Quickstart

quickstart.py Python

from tcglookup import TcgLookupClient
import os

# Initialize the client
client = TcgLookupClient(api_key=os.getenv("TCG_API_KEY"))

# Search for cards
results = client.cards.search(q="charizard", game="pokemon", limit=5)
for card in results.data:
    print(card.name, card.prices.raw.near_mint.tcgplayer.market)

# Get a specific card
card = client.cards.get("019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2")
print(card.name, card.set.name)

# Check rate limit after any call
print(client.rate_limit.remaining, "/", client.rate_limit.limit)

API Surface

client.cards.search() Search & batch lookup

# Keyword search
results = client.cards.search(q="black lotus", game="mtg", limit=10)

# Batch lookup by IDs — auto-chunks beyond 20
ids = ["uuid1", "uuid2"]  # any number
results = client.cards.search(ids=ids)

client.cards.get(id) Single card with full price breakdown

card = client.cards.get("019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2")
print(card.prices.raw.near_mint.tcgplayer.market)
print(card.prices.graded.psa["10"].ebay.avg_7d)  # Trader+

client.cards.history(id, period) Trader+ required

history = client.cards.history(card.id, period="30d")
for point in history.data:
    print(point.date, point.near_mint.tcgplayer.market)

client.sets.list() / client.games.list() Browse sets and games

sets = client.sets.list(game="pokemon", limit=10)
games = client.games.list()

Context manager Auto-close connections

with TcgLookupClient(api_key="tlk_live_...") as client:
    results = client.cards.search(q="pikachu")
# Connection closed automatically

Error Handling

error-handling.py

from tcglookup import (
    TcgLookupClient,
    AuthenticationError,
    PlanAccessError,
    NotFoundError,
    RateLimitError,
)

try:
    card = client.cards.get("some-id")
except AuthenticationError:
    print("Invalid API key")
except PlanAccessError as e:
    print(f"Plan required: {e.required_plan}")
except NotFoundError:
    print("Card not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

Rate Limit Headers

rate-limits.py

client.cards.search(q="pikachu")

# Inspect rate limit state after any request
print(client.rate_limit.limit)      # 100000
print(client.rate_limit.remaining)  # 99987
print(client.rate_limit.reset)      # Unix timestamp

Links

Start building with Python

Get your free API key and query card prices in minutes.

Get Free API Key Read the Docs