v1 · legacyDocs for the previous API generation. v1 endpoints keep working, but new work should target v2. See v2 Quickstart.

Quick Start Guide

Get started with the Cardog v1 API in minutes.

This guide walks through your first API call: looking up a vehicle by VIN.

Get Started

To start using the Cardog API:

  1. Create an account at cardog.app
  2. Create an API key in the API Keys section
  3. Install the official TypeScript client:
bash
npm install @cardog/api
# or
pnpm add @cardog/api
  1. Initialize the client:
typescript
import { CardogClient } from "@cardog/api";

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

Or use REST directly:

bash
curl "https://api.cardog.app/v1/vin/1HGCM82633A123456" \
   -H "x-api-key: your-api-key"

Make Your First API Call

Look up a vehicle by its VIN.

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

const client = new CardogClient({ apiKey: "your-api-key" });

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

Response:

Example

1 keys
"response": {
"variants": [
0: {10 items}
]
}

Common Use Cases

Other common calls:

Get Market Analysis

// Get comprehensive market analysis by VIN
const analysis = await client.market.analysis("1HGCM82633A123456");
console.log(analysis.medianPrice);
console.log(analysis.totalListings);

// Or get market overview by make/model/year
const overview = await client.market.overview("Toyota", "Camry", 2022);
console.log(overview.pricing.median);

Check Fuel Prices

// Find gas stations near coordinates
const stations = await client.fuel.search({
  lat: 37.7749,
  lng: -122.4194,
  radius: 10,
  fuelType: "REGULAR",
});

console.log(stations[0].name);
console.log(stations[0].price);

Search Listings

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

for (const listing of results.data) {
  console.log(`${listing.year} ${listing.make} ${listing.model} - $${listing.price}`);
}

Error Handling

The API uses standard HTTP status codes. The TypeScript client throws a typed error:

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

const client = new CardogClient({ apiKey: "your-api-key" });

try {
  const vehicle = await client.vin.decode("INVALID");
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status);  // 400
    console.log(error.code);    // "INVALID_VIN"
    console.log(error.message); // Human-readable message
  }
}

Next Steps

Pages to read next:

  1. VIN decoding: how VINs are structured and decoded
  2. Market Analysis API: pricing data
  3. Fuel API: real-time fuel prices

Need Help?