@cardog/api

@cardog/api

Official TypeScript client for the Cardog API
Vehicle data, market analysis, VIN decoding, and more.

Documentation · Get API Key · Pricing

Installation

npm install @cardog/api
# or
pnpm add @cardog/api
# or
yarn add @cardog/api

For React hooks, also install:

npm install @tanstack/react-query

Quick Start

import { CardogClient } from "@cardog/api";

const client = new CardogClient({
  apiKey: "your-api-key", // Get one at https://cardog.app
});

// Decode a VIN
const vehicle = await client.vin.decode("1HGCM82633A123456");
console.log(vehicle.make, vehicle.model, vehicle.year);
// Honda Accord 2003

// Get market analysis
const market = await client.market.overview("Toyota", "Camry", 2022);
console.log(market.medianPrice, market.totalListings);

// Search listings
const listings = await client.listings.search({
  makes: ["Toyota"],
  year: { min: 2020, max: 2024 },
  price: { max: 50000 },
});

React Hooks

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { CardogClient } from "@cardog/api";
import { createHooks } from "@cardog/api/react";

const queryClient = new QueryClient();
const client = new CardogClient({ apiKey: "your-api-key" });
const { useVinDecode, useMarketOverview, useListingsSearch } = createHooks(client);

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <VehicleLookup />
    </QueryClientProvider>
  );
}

function VehicleLookup() {
  const { data, isLoading, error } = useVinDecode("1HGCM82633A123456");

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data?.make} {data?.model} ({data?.year})
    </div>
  );
}

API Reference

VIN Decoding

// Decode a VIN
const vehicle = await client.vin.decode("1HGCM82633A123456");

// Decode from image (base64)
const result = await client.vin.image(base64Image);

Market Analysis

// Market overview for a specific vehicle
const overview = await client.market.overview("Toyota", "Camry", 2022);

// Price distribution
const pricing = await client.market.pricing("Honda", "Civic", 2021);

// Geographic breakdown
const geography = await client.market.geography("Ford", "F-150", 2023);

// Market trends over time
const trends = await client.market.trends("Tesla", "Model 3", 2022, "month");

// Listing market position
const position = await client.market.position("listing-id");

// Overall market pulse
const pulse = await client.market.pulse({
  priceRangeMin: 20000,
  priceRangeMax: 50000,
});

Vehicle Listings

// Search listings with filters
const results = await client.listings.search({
  makes: ["Toyota", "Honda"],
  models: { Toyota: ["Camry", "Corolla"] },
  year: { min: 2020, max: 2024 },
  price: { min: 15000, max: 40000 },
  odometer: { max: 50000 },
  bodyStyles: ["Sedan", "SUV"],
  fuelTypes: ["Gasoline", "Hybrid"],
});

// Get listing count
const count = await client.listings.count({ makes: ["BMW"] });

// Get facets for filtering UI
const facets = await client.listings.facets({ makes: ["Mercedes-Benz"] });

// Get specific listing
const listing = await client.listings.getById("listing-id");

Safety Recalls

// Search recalls
const recalls = await client.recalls.search({
  country: "us", // or "ca" for Canada
  makes: ["Toyota"],
  models: ["RAV4"],
  year: { min: 2019, max: 2023 },
});

Research & Specs

// Get vehicle lineup for a make
const lineup = await client.research.lineup("Toyota");

// Get model year details
const modelYear = await client.research.modelYear("Toyota", "Camry", 2023);

// Get vehicle images
const images = await client.research.images("Toyota", "Camry", 2023);

// Get available colors
const colors = await client.research.colors("Honda", "Civic", 2024);

Fuel & Charging

// Find gas stations
const gasStations = await client.fuel.search({
  lat: 43.6532,
  lng: -79.3832,
  radius: 10,
  fuelType: "REGULAR",
});

// Find EV charging stations
const chargers = await client.charging.search({
  lat: 43.6532,
  lng: -79.3832,
  radius: 25,
  minPower: 50, // kW
});

Locations

// Search dealer/seller locations
const dealers = await client.locations.search({
  lat: 43.6532,
  lng: -79.3832,
  radius: 50,
});

// Get seller details
const seller = await client.locations.getById("seller-id");

EPA Efficiency

// Search EPA fuel economy data
const efficiency = await client.efficiency.search({
  make: "Toyota",
  model: "Prius",
  year: 2023,
});

NHTSA Complaints

// Search vehicle complaints
const complaints = await client.complaints.search({
  make: "Ford",
  model: "Explorer",
  year: { min: 2020, max: 2023 },
});

Error Handling

import { CardogClient, APIError } from "@cardog/api";

try {
  const data = await client.vin.decode("INVALID");
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status);  // HTTP status code
    console.log(error.code);    // Error code (e.g., "INVALID_VIN")
    console.log(error.message); // Human-readable message
    console.log(error.data);    // Additional error details
  }
}

Query Keys

For manual React Query integration:

import { queryKeys } from "@cardog/api";

// Use in custom queries
const { data } = useQuery({
  queryKey: queryKeys.vin.decode("1HGCM82633A123456"),
  queryFn: () => client.vin.decode("1HGCM82633A123456"),
});

// Available key factories
queryKeys.vin.decode(vin)
queryKeys.market.overview(make, model, year)
queryKeys.listings.search(params)
queryKeys.recalls.search(params)
// ... and more

Configuration

const client = new CardogClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.cardog.app", // Default
});

// Update config at runtime
client.setConfig({
  apiKey: "new-api-key",
});

Pricing

Plan	Requests/mo	Price	Best For
Free	100	$0	Testing & development
Pro	10,000	$29/mo	Small apps & side projects
Business	100,000	$199/mo	Production applications
Enterprise	Unlimited	Custom	High-volume integrations

All plans include access to all API endpoints. View full pricing →

Links

• API Documentation
• Get API Key
• Pricing
• GitHub Issues

Related Packages

• @cardog/corgi - Offline VIN decoder (no API key needed)

License

MIT License - see LICENSE for details.