Metadata-Version: 2.4
Name: cardapi
Version: 0.1.0
Summary: Python SDK for the CardAPI credit card data API
License: MIT
Project-URL: Homepage, https://cardapi.dev
Project-URL: Documentation, https://cardapi.dev/docs
Project-URL: Repository, https://github.com/felixsingerman/carddb
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# cardapi

Official Python SDK for the [CardAPI](https://cardapi.dev) — the most comprehensive credit card data API for the US and Canada.

## Install

```bash
pip install cardapi
```

Or install from source:

```bash
pip install /path/to/sdk-python
```

## Quick Start

```python
from cardapi import CardAPI

client = CardAPI(api_key="ck_live_xxxxx")

# List Canadian cards
cards = client.get_cards(country="CA")

# Get a specific card
card = client.get_card("chase-sapphire-preferred")

# Search
results = client.search_cards("sapphire")

# Best cards for a spending category
best = client.get_best_cards("dining", country="US", limit=5)

# Compare cards side by side
compared = client.compare_cards(["chase-sapphire-preferred", "amex-gold"])

# Card change history (Pro+ tier)
history = client.get_card_history("chase-sapphire-preferred")

# Transfer partners for a card
transfers = client.get_card_transfers("chase-sapphire-preferred")

# Issuers
issuers = client.get_issuers()
issuer = client.get_issuer("chase")

# Spending categories
categories = client.get_categories()

# Transfer partner directory
partners = client.get_transfer_partners()

# Issuer application rules (e.g. Chase 5/24)
rules = client.get_application_rules(issuer="chase")

# Database stats
stats = client.get_stats()

# Your API usage and limits
usage = client.get_usage()
```

## Custom Base URL

```python
client = CardAPI(
    api_key="ck_live_xxxxx",
    base_url="http://localhost:3100",
)
```

## Error Handling

```python
from cardapi import CardAPI, CardAPIError

client = CardAPI(api_key="ck_live_xxxxx")

try:
    card = client.get_card("nonexistent-card")
except CardAPIError as e:
    print(e.status_code)  # 404
    print(e.code)         # "not_found"
    print(str(e))         # "Card not found"
```

## API Reference

All methods return the raw API response as a Python `dict`.

| Method | Description |
|--------|-------------|
| `get_cards(country, issuer, limit, offset)` | List cards with optional filters |
| `get_card(slug)` | Get a single card by slug |
| `search_cards(query, country)` | Full-text search |
| `compare_cards(slugs)` | Side-by-side comparison |
| `get_best_cards(category, country, limit)` | Best cards for a spending category |
| `get_card_history(slug)` | Offer change history (Pro+) |
| `get_card_transfers(slug)` | Transfer partners for a card |
| `get_issuers()` | List all issuers |
| `get_issuer(slug)` | Get a single issuer |
| `get_categories()` | List spending categories |
| `get_transfer_partners(currency)` | Transfer partner directory |
| `get_application_rules(issuer)` | Issuer application restrictions |
| `get_stats()` | Database stats |
| `get_usage()` | Your API key usage and limits |

## Get an API Key

Sign up at [cardapi.dev/portal](https://cardapi.dev/portal) — free tier includes 100 requests/day.
