Metadata-Version: 2.4
Name: tcglookup
Version: 0.1.0
Summary: Python SDK for TCG Price Lookup — live trading card prices across Pokemon, MTG, Yu-Gi-Oh, Lorcana, One Piece, SWU, Flesh and Blood
Project-URL: Homepage, https://tcgpricelookup.com/tcg-api
Project-URL: Documentation, https://tcgpricelookup.com/tcg-api
Project-URL: Repository, https://github.com/TCG-Price-Lookup/tcglookup-py
Project-URL: Issues, https://github.com/TCG-Price-Lookup/tcglookup-py/issues
Author-email: TCG Price Lookup <contact@tcgpricelookup.com>
License: MIT
License-File: LICENSE
Keywords: card-prices,ebay,flesh-and-blood,lorcana,mtg,one-piece,pokemon,star-wars-unlimited,tcg,tcgplayer,trading-card-game,yugioh
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# tcglookup-py

[![PyPI version](https://img.shields.io/pypi/v/tcglookup.svg)](https://pypi.org/project/tcglookup/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Powered by TCG Price Lookup](https://img.shields.io/badge/powered%20by-TCG%20Price%20Lookup-purple.svg)](https://tcgpricelookup.com/tcg-api)

The official Python SDK for the [**TCG Price Lookup API**](https://tcgpricelookup.com/tcg-api) — live trading card prices across **Pokemon, Magic: The Gathering, Yu-Gi-Oh!, Disney Lorcana, One Piece TCG, Star Wars: Unlimited, and Flesh and Blood**.

One API for every major trading card game. TCGPlayer market prices, eBay sold averages, and PSA / BGS / CGC graded comps — all in one place.

## Install

```bash
pip install tcglookup
```

## Quickstart

```python
from tcglookup import TcgLookupClient

client = TcgLookupClient(api_key="tlk_live_...")

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

# Get a single card by ID
card = client.cards.get("a3f8c1e2-...")
print(card["name"], card["prices"])

# Daily price history (Trader plan and above)
history = client.cards.history("a3f8c1e2-...", period="30d")
for day in history["data"]:
    print(day["date"], day["prices"])

# List all supported games
for game in client.games.list()["data"]:
    print(game["slug"], game["name"], game["count"], "cards")
```

## Get an API key

Sign up at [tcgpricelookup.com/tcg-api](https://tcgpricelookup.com/tcg-api). Free tier includes 10,000 requests per month with TCGPlayer market prices. Trader plan unlocks eBay sold averages, PSA / BGS / CGC graded prices, and full price history.

## API surface

### Cards

```python
client.cards.search(
    q="blue-eyes white dragon",
    game="yugioh",       # pokemon | mtg | yugioh | onepiece | lorcana | swu | fab
    set="lob",           # set slug
    limit=20,
    offset=0,
)

client.cards.get("<card-uuid>")

client.cards.history("<card-uuid>", period="30d")  # 7d | 30d | 90d | 1y
```

### Sets

```python
client.sets.list(game="mtg", limit=50)
```

### Games

```python
client.games.list()
```

### Batch lookups

Pass an iterable of IDs and the SDK auto-chunks into 20-ID batches:

```python
results = client.cards.search(ids=["uuid1", "uuid2", ..., "uuid100"])
```

## Error handling

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

client = TcgLookupClient(api_key="tlk_live_...")

try:
    history = client.cards.history("<uuid>", period="1y")
except AuthenticationError:
    print("Bad API key")
except PlanAccessError:
    print("History requires Trader plan — upgrade at tcgpricelookup.com/tcg-api")
except NotFoundError:
    print("That card doesn't exist")
except RateLimitError:
    print(f"Rate limited. Quota: {client.rate_limit.remaining}/{client.rate_limit.limit}")
```

## Rate limits

After every successful request, the most recent rate-limit headers are available on the client:

```python
client.cards.search(q="pikachu")
print(client.rate_limit.remaining, "/", client.rate_limit.limit)
```

## Use as a context manager

```python
with TcgLookupClient(api_key="tlk_live_...") as client:
    cards = client.cards.search(q="black lotus", game="mtg")
# HTTP connection pool is closed automatically
```

## Sister SDKs

- [tcglookup-js](https://github.com/TCG-Price-Lookup/tcglookup-js) — JavaScript / TypeScript
- [tcglookup-go](https://github.com/TCG-Price-Lookup/tcglookup-go) — Go
- [tcglookup-rs](https://github.com/TCG-Price-Lookup/tcglookup-rs) — Rust
- [tcglookup-php](https://github.com/TCG-Price-Lookup/tcglookup-php) — PHP
- [tcglookup CLI](https://www.npmjs.com/package/tcglookup) — terminal client
- [tcg-api-examples](https://github.com/TCG-Price-Lookup/tcg-api-examples) — runnable code samples in 8 languages
- [tcg-discord-bot](https://github.com/TCG-Price-Lookup/tcg-discord-bot) — self-hosted Discord bot with slash commands

The full developer ecosystem index lives at **[awesome-tcg](https://github.com/TCG-Price-Lookup/awesome-tcg)**.

## License

MIT — see [LICENSE](LICENSE).

---

Built by [TCG Price Lookup](https://tcgpricelookup.com). Get a free API key at [tcgpricelookup.com/tcg-api](https://tcgpricelookup.com/tcg-api).
