cardog 0.1.0

Official Python SDK for the Cardog API

Cardog Python SDK

Official Python SDK for the Cardog API — automotive intelligence, VIN decoding, market analytics, and more.

Installation

pip install cardog

Quick Start

from cardog import Cardog

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

# Decode a VIN
vehicle = client.vin.decode("1HGCM82633A123456")
print(vehicle.components.vehicle.make)  # "Honda"

# Search listings
results = client.listings.search(
    makes=["Toyota"],
    year_min=2020,
    price_max=30000,
)
for listing in results.listings:
    print(f"{listing.year} {listing.make} {listing.model} - ${listing.price}")

# Market overview
overview = client.market.overview("Honda", "Civic", 2022)
print(f"Median price: ${overview.median_price}")

# Recalls
recalls = client.recalls.search("us", makes=["Tesla"])
print(f"Found {recalls.meta.count} recalls")

# EV charging stations
stations = client.charging.search(lat=43.65, lng=-79.38, radius=10)
for station in stations.stations:
    print(f"{station.name} - {station.network}")

# Fuel prices
fuel = client.fuel.get("regular", lat=43.65, lng=-79.38)
print(f"Current price: {fuel.current} {fuel.unit}")

Async Support

import asyncio
from cardog import AsyncCardog

async def main():
    client = AsyncCardog(api_key="your-api-key")

    vehicle = await client.vin.decode("1HGCM82633A123456")
    listings = await client.listings.search(makes=["Toyota"])

    await client.close()

asyncio.run(main())

Available Resources

Resource	Description
client.vin	VIN decoding (single, batch, image)
client.listings	Vehicle listing search, count, facets
client.market	Market analytics, pricing, trends, geography
client.recalls	US & Canadian vehicle recalls
client.charging	EV charging station search
client.fuel	Fuel prices and gas station search
client.research	Vehicle variants, specs, images
client.locations	Dealer/seller search
client.safety	NHTSA safety ratings
client.efficiency	EPA fuel economy data
client.complaints	NHTSA complaints
client.history	Vehicle history reports

Configuration

client = Cardog(
    api_key="your-api-key",
    base_url="https://api.cardog.io/v1",  # default
    timeout=30.0,                          # seconds
    max_retries=2,                         # retry on 429/5xx
)

Error Handling

from cardog import Cardog, NotFoundError, RateLimitError, AuthenticationError

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

try:
    vehicle = client.vin.decode("INVALID")
except NotFoundError:
    print("VIN not found")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")

Type Safety

All responses are Pydantic models with full type hints. Your IDE will provide autocomplete for every field.

result = client.market.overview("Toyota", "Camry", 2023)
# IDE knows result.avg_price is float, result.total_listings is int, etc.

License

MIT