# Cardog Python SDK

Official Python SDK for the [Cardog API](https://docs.cardog.app) — automotive intelligence, VIN decoding, market analytics, and more.

## Installation

```bash
pip install cardog
```

## Quick Start

```python
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

```python
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

```python
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

```python
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.

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

## License

MIT
