cardapi

Official Python SDK for the CardAPI — the most comprehensive credit card data API for the US and Canada.

Get a free key (100 calls a day, no card): cardapi.dev/signup. Plans and the fields each returns: cardapi.dev/pricing.

Install

pip install cardapi

Or install from source:

pip install /path/to/sdk-python

Quick Start

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:

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

Reward rates

Each card's reward_rates say where a rate applies in categories (slugs from /v1/categories), merchant, booking_channel and choice_group; match on those. category_slug is a label built from them, unique on the card within a rotating quarter, so the same rate reads the same on every card: <categories>[:<merchant>][@portal|@direct][#choice][~<tag>], for example dining, groceries+gas, airlines:united-airlines, travel@portal, dining#choice and other (the base rate). A ~tag such as ~3x is added only when two rates of one card would otherwise share a label, and can change when the card's other rates change.

Options

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

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.

Get an API Key

Sign up at cardapi.dev/portal — free tier includes 100 requests/day.