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:

  1. Create an account at cardog.app
  2. Create an API key in the API Keys section
  3. Use the API key in your requests:
curl "https://api.cardog.io/v1/vin/12345678901234567" \
   -H "x-api-key: your-api-key"

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.

cURL

curl "https://api.cardog.io/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

cURL

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

// Get market analysis for a vehicle
const response = await fetch(
  'https://api.cardog.io/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.io/v1/market/analysis/1HGCM82633A123456',
  headers={'x-api-key': 'your-api-key'}
)
data = response.json()

Check Fuel Prices

cURL

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

// Get fuel prices in a location
const response = await fetch(
  'https://api.cardog.io/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.io/v1/fuel/gas', params={
  'country': 'US',
  'region': 'CA',
  'city': 'San Francisco'
}, headers={'x-api-key': 'your-api-key'})
data = response.json()

Find Similar Listings

cURL

curl "https://api.cardog.io/v1/market/listings/1HGCM82633A123456/similar?limit=5" \
   -H "x-api-key: your-api-key"

// Find similar vehicles
const response = await fetch(
  'https://api.cardog.io/v1/market/listings/1HGCM82633A123456/similar?' + new URLSearchParams({
    limit: 5
  }),
  {
    headers: {
      'x-api-key': 'your-api-key'
    }
  }
)
const data = await response.json()

# Find similar vehicles
import requests
response = requests.get(
  'https://api.cardog.io/v1/market/listings/1HGCM82633A123456/similar',
  params={'limit': 5},
  headers={'x-api-key': 'your-api-key'}
)
data = response.json()

Error Handling

The API uses standard HTTP status codes and provides detailed error messages:

try {
  const response = await fetch(
    'https://api.cardog.io/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.io/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:

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

Need Help?

Was this page helpful?