Skip to main content

cardog

The Python SDK for the Cardog API — the system of record for every vehicle. Decode VINs, resolve names to permanent refs, search live listings, quote the market, and check each market's recalls (Transport Canada, NHTSA and more) behind one key.

pip install cardog
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

# Free text enters exactly once. Everything after this takes refs.
result = client.v2.entities.resolve("2021 Civic")
ref = result.best.ref            # "model-year:honda/civic/2021"

identity = client.v2.vin.get_by_vin("2HGFC2F53MH500001")
recalls = client.v2.vin.recalls("2HGFC2F53MH500001")
quote = client.v2.quotes.get_by_ref(ref)

VIN decode reaches trim on 99.77% of Canadian VINs, the market US-built decoders stop short on. Types and methods are generated from the same OpenAPI contract the API validates against — this SDK and the TypeScript one are siblings, not translations.

Errors are instructions. Every non-2xx v2 response raises a typed CardogAPIError carrying code, hint, docs_url, and nearest-ref suggestions, so a wrong ref is corrected on the next call instead of silently matched to the wrong vehicle.

Whole platform in one fetch: https://cardog.app/docs.md

Quick start — resolve → refs → query

v2 is ref-native: free text enters the API in exactly one place (entities.resolve), everything else speaks canonical refs like make:tesla or model-year:toyota/rav4/2021.

from cardog import Cardog

client = Cardog(api_key="your-api-key")

# 1. Free text → refs with confidence (the front door)
resolved = client.v2.entities.resolve("tesla model y")
best = resolved.best          # None when nothing clears the confidence floor —
                              # the API never guesses for you
print(best.ref)               # "model:tesla/model-y"

# 2. Dereference a ref: node + parents/children + counts + links
detail = client.v2.entities.get_by_ref(best.ref)
print(detail.name, detail.counts)

# 3. Query with refs — never fuzzy, never guessed
results = client.v2.listings.search(
    filters={
        "makes": ["make:tesla"],
        "price": {"max": 60000},
        "year": {"min": 2022},
    },
    sort="price",
    order="asc",
)
for listing in results.listings:
    print(f"{listing.year} {listing.make} {listing.model} — ${listing.price:,.0f}")

VIN → identity, recalls, market

# VIN → graph identity card (refs, grains, links)
identity = client.v2.vin.get_by_vin("5YJSA1E28MF420053")
print(identity.make, identity.model, identity.refs.model_year)

# Batch decode (metered per VIN, max 1000) — one bad VIN fails its own row, never the batch
batch = client.v2.vin.batch(["5YJSA1E28MF420053", "1HGCV1F34LA045661"])

# Recalls affecting a VIN (Transport Canada + NHTSA fused)
recalls = client.v2.recalls.vin("5YJSA1E28MF420053")

# VIN → market instrument bridge, quotes, tape
instrument = client.v2.vin.instrument("5YJSA1E28MF420053")
quote = client.v2.quotes.get_by_ref("model-year:toyota/rav4/2021")
bars = client.v2.tape.history("model-year:toyota/rav4/2021", window="3m")

Errors are instructions

Every non-2xx v2 response raises CardogAPIError carrying the full error envelope — code is machine-dispatchable, hint says what to do next, and suggestions carries nearest-ref candidates so a typo'd ref self-corrects in one turn:

from cardog import Cardog, CardogAPIError

client = Cardog(api_key="your-api-key")

try:
    client.v2.listings.search(filters={"makes": ["make:teslla"]})
except CardogAPIError as e:
    print(e.status_code)   # 400
    print(e.code)          # "unknown_entity_refs"
    print(e.hint)          # "Resolve free text to refs at GET /v2/entities/resolve?q=teslla"
    print(e.docs_url)      # "https://cardog.app/docs/errors/unknown_entity_refs.md"
    print(e.refs)          # ["make:teslla"]
    for s in e.suggestions or []:
        print(s["invalid"], "→", [n["ref"] for n in s["nearest"]])
        # "make:teslla" → ["make:tesla"]   (advisory — never auto-applied)

Async

AsyncCardog mirrors the whole surface:

import asyncio
from cardog import AsyncCardog

async def main():
    client = AsyncCardog(api_key="your-api-key")
    identity = await client.v2.vin.get_by_vin("5YJSA1E28MF420053")
    results = await client.v2.listings.search(filters={"makes": ["make:tesla"]})
    await client.close()

asyncio.run(main())

The v2 surface

Group Methods
client.v2.entities browse(domain, ...) · resolve(q, ...) · get_by_ref(ref)
client.v2.vin get_by_vin(vin) · batch(vins) · recalls(vin) · listings(vin) · instrument(vin)
client.v2.specs catalog() · sheet(ref, trim=...) · sheet_by_build(code)
client.v2.listings search(...) · count(...) · facets(...) · by_vin(vin) · by_id(id)
client.v2.instruments search(q=..., limit=...) · get_by_ref(ref, window=...)
client.v2.quotes get_by_ref(ref) · get_many(refs)
client.v2.tape live(limit=...) · history(ref, window=...)
client.v2.recalls vin(vin) · entity(ref) · feed() · stats() · get_by_ref(ref)
client.v2.safety ratings(ref) · complaints(ref, page=..., limit=...)
platform meta client.v2.pricing() · client.v2.openapi() (both unauthenticated)

The machine-readable rate card (pricing()) plus the X-Credits-* response headers let you budget mid-task; openapi() returns the same contract this SDK is generated from. The client keeps the last set of those headers parsed on client.last_credits, errors included (a 402 states the budget too):

client.v2.vin.get_by_vin("5YJSA1E28MF420053")
credits = client.last_credits  # a Credits, or None before any metered call
print(credits.rate, credits.remaining, credits.allowance, credits.reset, credits.source)
# rate: what that call cost · remaining: allowance headroom + pack balance (-1 = custom plan)
# reset: when the allowance rolls over · source: "allowance" | "pack" | "overage", None when nothing was debited

Errors carry the envelope: err.code to branch on, err.message on its own, err.hint for what to do next. str(err) is the log line, [status] (code) message.

v1 (legacy)

The pre-1.0 resources keep working unchanged — client.vin.decode(...), client.listings.search(...), client.market, client.recalls, client.charging, client.fuel, and the rest ride under the same client with the same signatures. New integrations should target client.v2.*.

One behavioural note for 1.0: api_key is now optional (Cardog() works) so the unauthenticated platform-meta routes are reachable without a key. Everything else requires a key, exactly as before.

Configuration

client = Cardog(
    api_key="your-api-key",          # or omit for pricing()/openapi() only
    base_url="https://api.cardog.app/v1",  # default; a trailing /v1 is stripped for v2 calls
    timeout=30.0,
    max_retries=2,                   # retries 408/429/5xx with backoff, honours Retry-After
)

Regenerating the v2 surface (maintainers)

make generate    # emit openapi.v2.json from @cardog/contracts, regenerate src/cardog/v2/
make check       # generate twice + assert zero diff + run tests

src/cardog/v2/ (types + group resources) is generated by scripts/generate.py from packages/contracts/dist/openapi.v2.json — do not edit those files by hand. The method map (operationId → Python method) lives in the generator and is validated against the spec on every run.

License

MIT


mcp-name: app.cardog/mcp

Metadata

Release files for cardog 3.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cardog 3.7.0
File Size Uploaded Provenance Actions
cardog-3.7.0.tar.gz 174.8 kB With provenance Details for cardog-3.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cardog 3.7.0
File Interpreter ABI Platform Actions
cardog-3.7.0-py3-none-any.whl Python 3 none any Details for cardog-3.7.0-py3-none-any.whl

Total release size: 278.2 kB

Release files / cardog-3.7.0.tar.gz

Download URL cardog-3.7.0.tar.gz
Size 174.8 kB
Tags Source
SHA-256 checksum
How to use checksums
d73150e019c8b2cd474c83827c8d962c3f33c43af7f24269f6f5cbf2b3868a10
BLAKE2b-256 checksum
How to use checksums
1519d8398710d2ccd86573e91a9d405c88ca5e85fcfd8aacb77f179d11995e21
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / cardog-3.7.0-py3-none-any.whl

Download URL cardog-3.7.0-py3-none-any.whl
Size 103.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
522fde1b94acfe94c8bd0e8da0a3bc16f66b24d10f5217faaae7352e0fb74c63
BLAKE2b-256 checksum
How to use checksums
c335b236b7b687402afbcedf4a039de6392b0b1437bedfbe44e5b64b8c2420b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for cardog 3.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cardog-3.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page