Quick Start Guide

This guide will help you make your first API call and understand the basics of working with the Cardog API. We'll walk through a simple example of looking up vehicle information by VIN.

Get Started

To start using the Cardog API:

Create an account at cardog.app
Create an API key in the API Keys section
Install the official TypeScript client:

Install

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

Initialize the client:

Setup

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

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

Or use REST directly:

cURL

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

Try the API in Postman

Fork our collection to test API endpoints directly in Postman with pre-configured requests.

Make Your First API Call

Let's look up information about a vehicle using its VIN. This is a common first step in many automotive applications.

@cardog/api

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

cURL

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

Response

{
  "variants": [
    {
      "id": "Hond-03CA-d35249a9eb0e",
      "make": "Honda",
      "model": "Accord",
      "year": 2003,
      "trim": "2dr Cpe LX Manual",
      "msrp": 25200,
      "styleName": "Honda Accord",
      "region": "CA",
      "bodyStyle": "2dr Cpe LX Manual",
      "spec": {
        "Fuel": {
          "Fuel": "Gasoline",
          "Fuel Capacity": "64.7 L",
          "Fuel Consumption: City": "9.0 L/100 km",
          "Fuel Consumption: Highway": "6.4 L/100 km",
          "Fuel Consumption: City/HWY Combined": "6.4 - 9.0 L/100 km"
        },
        "Safety": {
          "Brake": "Front Disc Rear Drum",
          "Knee Air Bag": false,
          "Driver Air Bag": true,
          "Brake ABS System": true,
          ...
        },
        "Comfort": {
          "Seat-Massage": false,
          "Climate Control": false,
          "Air Conditioning": true,
          "Cooled Rear Seat(s)": false,
          "Heated Rear Seat(s)": false,
          ...
        }
      }
    }
  ]
}

Common Use Cases

Here are some popular API calls to get you started:

Get Market Analysis

@cardog/api

// 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);

cURL

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

fetch

// Get market analysis for a vehicle
const response = await fetch(
  'https://api.cardog.app/v1/market/analysis/1HGCM82633A123456',
  {
    headers: {
      'x-api-key': 'your-api-key'
    }
  }
)
const data = await response.json()

# Get market analysis for a vehicle
import requests
response = requests.get(
  'https://api.cardog.app/v1/market/analysis/1HGCM82633A123456',
  headers={'x-api-key': 'your-api-key'}
)
data = response.json()

Check Fuel Prices

@cardog/api

// 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);

cURL

curl "https://api.cardog.app/v1/fuel/gas?country=US&region=CA&city=San%20Francisco" \
   -H "x-api-key: your-api-key"

fetch

// Get fuel prices in a location
const response = await fetch(
  'https://api.cardog.app/v1/fuel/gas?' + new URLSearchParams({
    country: 'US',
    region: 'CA',
    city: 'San Francisco'
  }),
  {
    headers: {
      'x-api-key': 'your-api-key'
    }
  }
)
const data = await response.json()

# Get fuel prices in a location
import requests
response = requests.get('https://api.cardog.app/v1/fuel/gas', params={
  'country': 'US',
  'region': 'CA',
  'city': 'San Francisco'
}, headers={'x-api-key': 'your-api-key'})
data = response.json()

Search Listings

@cardog/api

// 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}`);
}

cURL

curl "https://api.cardog.app/v1/listings?makes=Toyota,Honda&yearMin=2020&yearMax=2024" \
   -H "x-api-key: your-api-key"

fetch

// Search listings
const response = await fetch(
  'https://api.cardog.app/v1/listings?' + new URLSearchParams({
    makes: 'Toyota,Honda',
    yearMin: '2020',
    yearMax: '2024'
  }),
  {
    headers: {
      'x-api-key': 'your-api-key'
    }
  }
)
const data = await response.json()

# Search listings
import requests
response = requests.get(
  'https://api.cardog.app/v1/listings',
  params={'makes': 'Toyota,Honda', 'yearMin': 2020, 'yearMax': 2024},
  headers={'x-api-key': 'your-api-key'}
)
data = response.json()

Error Handling

The API uses standard HTTP status codes. The TypeScript client provides typed error handling:

@cardog/api

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
  }
}

fetch

try {
  const response = await fetch(
    'https://api.cardog.app/v1/vin/invalid-vin',
    {
      headers: {
        'x-api-key': 'your-api-key'
      }
    }
  )

  if (!response.ok) {
    if (response.status === 400) {
      console.error('Invalid VIN provided')
    } else if (response.status === 429) {
      console.error('Rate limit exceeded')
    } else {
      console.error('Unexpected error:', response.status)
    }
  }

  const data = await response.json()
} catch (error) {
  console.error('Network error:', error)
}

import requests

try:
    response = requests.get(
        'https://api.cardog.app/v1/vin/invalid-vin',
        headers={'x-api-key': 'your-api-key'}
    )

    if response.status_code == 400:
        print('Invalid VIN provided')
    elif response.status_code == 429:
        print('Rate limit exceeded')
    elif not response.ok:
        print(f'Unexpected error: {response.status_code}')
    else:
        data = response.json()

except requests.exceptions.RequestException as error:
    print(f'Network error: {error}')

Next Steps

Now that you've made your first API call, you can:

Learn about VIN decoding to better understand vehicle identification
Explore the Market Analysis API for pricing insights
Check out the Fuel API for real-time fuel prices

Need Help?

Join our Discord community
Check our API Status
Contact support