Metadata-Version: 2.4
Name: cardapi
Version: 0.3.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
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: {"data": [...], "total": ..., "limit": ..., "offset": ...}
cards = client.get_cards(country="CA")
print(cards["total"])

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

# Search, optionally within one country
results = client.search_cards("sapphire")
canadian = client.search_cards("visa", country="CA")

# 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-credit-card", "american-express-gold-card"])

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

# Spending categories and point valuations
categories = client.get_categories()
valuations = client.get_reward_valuations()

# Issuer application rules (e.g. Chase 5/24) and product change paths
rules = client.get_application_rules(issuer="chase")
paths = client.get_product_changes(issuer="chase")

# Starter plan and above
perks = client.get_card_perks("american-express-gold-card")
credits = client.get_card_credits("american-express-gold-card")

# Pro plan and above
history = client.get_card_history("citi-custom-cash-card")
transfers = client.get_card_transfers("american-express-gold-card")
partners = client.get_transfer_partners(currency="MR")
notable = client.get_notable_offers(country="US")

# Database stats and your API usage
stats = client.get_stats()
usage = client.get_usage()
```

A runnable version is in [`examples/quickstart.py`](examples/quickstart.py):

```bash
CARDAPI_API_KEY=ck_live_... python examples/quickstart.py
```

## Options

```python
client = CardAPI(
    api_key="ck_live_xxxxx",
    base_url="http://localhost:3100",  # default: cardapi.client.DEFAULT_BASE_URL
    timeout=(5, 30),                   # (connect, read) seconds; the default
)
```

## 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"
    print(e.retry_after)  # seconds, when the server sent Retry-After (e.g. on 429)
```

Every HTTP error response raises `CardAPIError`, including ones whose body isn't JSON (their `code` is `"unknown"`). Connection failures and timeouts raise the usual `requests` exceptions, such as `requests.exceptions.Timeout`.

## API Reference

All methods return the API's JSON response as a Python `dict`.

| Method | Description |
|--------|-------------|
| `get_cards(country, issuer, limit, offset, network, card_type, max_annual_fee, no_annual_fee, credit_score, include_discontinued)` | List cards with optional filters, 25 per page unless you pass `limit` |
| `get_card(slug)` | Get a single card by slug |
| `search_cards(query, country, limit, offset)` | Search card and issuer names |
| `compare_cards(slugs)` | Side-by-side comparison of 2-5 cards |
| `get_best_cards(category, country, limit, max_annual_fee, no_annual_fee)` | Best cards for a spending category |
| `get_card_history(slug)` | Tracked field changes for a card (Pro+) |
| `get_card_perks(slug)` | Companion perks for a card (Starter+) |
| `get_card_credits(slug)` | Statement credits for a card (Starter+) |
| `get_card_transfers(slug)` | Transfer partners for a card (Pro+) |
| `get_issuers(country)` | List issuers |
| `get_issuer(slug)` | Get a single issuer |
| `get_categories()` | List spending categories |
| `get_transfer_partners(currency)` | Transfer partner directory (Pro+) |
| `get_application_rules(issuer)` | Issuer application restrictions |
| `get_reward_valuations()` | Cents-per-point valuations |
| `get_product_changes(issuer)` | Product change paths |
| `get_notable_offers(country)` | Recent notable offer changes (Pro+) |
| `get_offer_history(card_slug)` | Offer change history for a card (Pro+) |
| `create_webhook(url, events)` / `list_webhooks()` / `delete_webhook(id)` | Webhooks (Enterprise) |
| `get_stats()` | Database stats |
| `get_usage()` | Your account's usage (all keys) and limits |

## Get an API Key

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