CarGurus API Reference

Complete API documentation for extracting multi-market automotive data from CarGurus. All endpoints, parameters, response formats, and code examples for US, Canada, and UK markets.

API Overview

• Base URL: https://api.carapis.com/v1/parsers/cargurus
• Authentication: Bearer token in Authorization header
• Response Format: JSON
• Rate Limits: Vary by plan (100-2000 requests/minute)
• Success Rate: 99.9% with advanced anti-detection technology
• Multi-market Support: US, Canada, and UK markets

🔐 Authentication

All API requests require authentication using your API key:

// JavaScript
const headers = {
  Authorization: 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json',
};

# Python
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.carapis.com/v1/parsers/cargurus/search

📡 Endpoints

Search Vehicles

POST /search

Search for vehicles on CarGurus with various filters and parameters across US, Canada, and UK markets.

Request Parameters

Search Parameters

Parameter	Type	Required	Description	Example
query	string	Yes	Search term (brand, model, etc.)	"Ford F-150"
market	string	Yes	Target market (us, ca, uk)	"us"
max_price	number	No	Maximum price in market currency	50000
min_price	number	No	Minimum price in market currency	20000
location	string	No	City, state, or region	"New York"
fuel_type	string	No	Fuel type filter	"gasoline"
transmission	string	No	Transmission type	"automatic"
year_from	number	No	Minimum year	2020
year_to	number	No	Maximum year	2023
mileage_max	number	No	Maximum mileage	100000
mileage_min	number	No	Minimum mileage	10000
limit	number	No	Number of results (max 100)	50
offset	number	No	Pagination offset	0
sort_by	string	No	Sort field	"price", "year", "deal_rating"
sort_order	string	No	Sort direction	"asc", "desc"

Market-Specific Parameters

Market Parameters

Market	Currency	Special Parameters	Description
US	USD	epa_rating, us_standards	EPA fuel economy ratings
Canada	CAD	province, bilingual	Provincial data, French support
UK	GBP	mot_status, uk_standards	MOT certification, UK regulations

Fuel Type Options

Available Fuel Types

Value	Description	Market Support
gasoline	Gasoline fuel	All markets
diesel	Diesel fuel	All markets
electric	Electric vehicles	All markets
hybrid	Hybrid vehicles	All markets
plug_in_hybrid	Plug-in hybrid	All markets
flex_fuel	Flex fuel	US only

Transmission Options

Transmission Types

Value	Description	Market Term
automatic	Automatic transmission	Automatic
manual	Manual transmission	Manual
cvt	Continuously variable transmission	CVT

Sort Options

Sorting Options

Field	Description	Example
price	Sort by price	{"sort_by": "price", "sort_order": "asc"}
year	Sort by year	{"sort_by": "year", "sort_order": "desc"}
deal_rating	Sort by CarGurus deal rating	{"sort_by": "deal_rating", "sort_order": "desc"}
mileage	Sort by mileage	{"sort_by": "mileage", "sort_order": "asc"}
date_added	Sort by listing date	{"sort_by": "date_added", "sort_order": "desc"}

Request Example

const searchRequest = {
  query: 'Ford F-150',
  market: 'us',
  max_price: 50000,
  location: 'New York',
  fuel_type: 'gasoline',
  transmission: 'automatic',
  year_from: 2020,
  limit: 20,
  sort_by: 'deal_rating',
  sort_order: 'desc',
};

Response Format

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "123456789",
        "title": "Ford F-150 XLT",
        "price": {
          "amount": 42000,
          "currency": "USD",
          "formatted": "$42,000",
          "negotiable": false
        },
        "deal_rating": {
          "score": 9.2,
          "label": "Great Deal",
          "explanation": "Priced $2,500 below market average"
        },
        "specifications": {
          "year": 2020,
          "mileage": 35000,
          "fuel_type": "Gasoline",
          "transmission": "Automatic",
          "engine_size": "3.5L V6",
          "power": "400 hp",
          "torque": "500 lb-ft",
          "drivetrain": "4WD",
          "mpg_city": 20,
          "mpg_highway": 26
        },
        "location": {
          "city": "New York",
          "state": "NY",
          "country": "United States",
          "postal_code": "10001",
          "coordinates": {
            "lat": 40.7128,
            "lng": -74.006
          }
        },
        "seller": {
          "name": "NYC Ford Dealership",
          "type": "dealer",
          "rating": 4.7,
          "reviews_count": 150,
          "certified": true,
          "contact": {
            "phone": "+1-212-555-0123",
            "email": "info@nycford.com"
          }
        },
        "features": ["Navigation System", "Leather Seats", "Towing Package", "Bluetooth Connectivity", "Backup Camera"],
        "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
        "url": "https://www.cargurus.com/...",
        "extracted_at": "2024-01-15T10:30:00Z",
        "last_updated": "2024-01-15T10:30:00Z"
      }
    ],
    "total_count": 1200,
    "search_metadata": {
      "query": "Ford F-150",
      "market": "us",
      "filters_applied": {
        "max_price": 50000,
        "location": "New York",
        "fuel_type": "gasoline"
      },
      "pagination": {
        "limit": 20,
        "offset": 0,
        "has_more": true
      }
    }
  }
}

Get Vehicle Details

GET /vehicle/\{id\}

Get detailed information about a specific vehicle by its ID.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Vehicle ID from search results

Request Example

const vehicleId = '123456789';
const response = await axios.get(`https://api.carapis.com/v1/parsers/cargurus/vehicle/$\{vehicleId\}`, {
  headers: {
    Authorization: `Bearer $\{API_KEY\}`,
    'Content-Type': 'application/json',
  },
});

Response Format

{
  "success": true,
  "data": {
    "vehicle": {
      "id": "123456789",
      "title": "Ford F-150 XLT",
      "description": "Well-maintained Ford F-150 with full service history...",
      "price": {
        "amount": 42000,
        "currency": "USD",
        "formatted": "$42,000",
        "negotiable": false,
        "price_history": [
          {
            "date": "2024-01-01",
            "price": 44000
          },
          {
            "date": "2024-01-15",
            "price": 42000
          }
        ]
      },
      "deal_rating": {
        "score": 9.2,
        "label": "Great Deal",
        "explanation": "Priced $2,500 below market average",
        "market_comparison": {
          "average_price": 44500,
          "price_difference": -2500,
          "percentile": 85
        }
      },
      "specifications": {
        "year": 2020,
        "mileage": 35000,
        "fuel_type": "Gasoline",
        "transmission": "Automatic",
        "engine_size": "3.5L V6",
        "power": "400 hp",
        "torque": "500 lb-ft",
        "drivetrain": "4WD",
        "mpg_city": 20,
        "mpg_highway": 26,
        "vin": "1FTEW1EG0JFA12345",
        "registration_date": "2020-03-15",
        "next_inspection": "2025-03-15"
      },
      "vehicle_history": {
        "owners": 2,
        "accident_free": true,
        "service_history": "Complete",
        "warranty": "Extended warranty until 2026",
        "import_history": "US vehicle"
      },
      "location": {
        "city": "New York",
        "state": "NY",
        "country": "United States",
        "postal_code": "10001",
        "coordinates": {
          "lat": 40.7128,
          "lng": -74.006
        }
      },
      "seller": {
        "name": "NYC Ford Dealership",
        "type": "dealer",
        "rating": 4.7,
        "reviews_count": 150,
        "certified": true,
        "contact": {
          "phone": "+1-212-555-0123",
          "email": "info@nycford.com",
          "website": "https://www.nycford.com"
        },
        "address": {
          "street": "123 Main Street",
          "city": "New York",
          "state": "NY",
          "postal_code": "10001",
          "country": "United States"
        },
        "business_hours": {
          "monday": "09:00-18:00",
          "tuesday": "09:00-18:00",
          "wednesday": "09:00-18:00",
          "thursday": "09:00-18:00",
          "friday": "09:00-18:00",
          "saturday": "09:00-16:00",
          "sunday": "Closed"
        }
      },
      "features": ["Navigation System", "Leather Seats", "Towing Package", "Bluetooth Connectivity", "Backup Camera", "Apple CarPlay", "Android Auto", "Heated Seats", "Cruise Control", "Lane Departure Warning"],
      "images": [
        {
          "url": "https://example.com/image1.jpg",
          "alt": "Front view",
          "primary": true
        },
        {
          "url": "https://example.com/image2.jpg",
          "alt": "Interior view",
          "primary": false
        }
      ],
      "url": "https://www.cargurus.com/...",
      "extracted_at": "2024-01-15T10:30:00Z",
      "last_updated": "2024-01-15T10:30:00Z"
    }
  }
}

Get Market Statistics

GET /statistics

Get market statistics and trends for the specified market.

Query Parameters

Parameter	Type	Required	Description	Example
market	string	Yes	Target market (us, ca, uk)	"us"
brand	string	No	Filter by brand	"Ford"
model	string	No	Filter by model	"F-150"
location	string	No	Filter by location	"New York"
period	string	No	Time period	"30d", "90d", "1y"

Request Example

const response = await axios.get('https://api.carapis.com/v1/parsers/cargurus/statistics', {
  params: {
    market: 'us',
    brand: 'Ford',
    model: 'F-150',
    location: 'New York',
    period: '90d',
  },
  headers: {
    Authorization: `Bearer $\{API_KEY\}`,
    'Content-Type': 'application/json',
  },
});

Response Format

{
  "success": true,
  "data": {
    "statistics": {
      "total_listings": 1200,
      "average_price": 42000,
      "price_range": {
        "min": 25000,
        "max": 75000,
        "median": 41000
      },
      "deal_rating_distribution": {
        "great_deals": 180,
        "good_deals": 420,
        "fair_deals": 480,
        "high_prices": 120
      },
      "price_trends": [
        {
          "date": "2024-01-01",
          "average_price": 42500,
          "listings_count": 1150
        },
        {
          "date": "2024-01-15",
          "average_price": 42000,
          "listings_count": 1200
        }
      ],
      "brand_distribution": [
        {
          "brand": "Ford",
          "count": 450,
          "percentage": 37.5
        },
        {
          "brand": "Chevrolet",
          "count": 380,
          "percentage": 31.7
        }
      ],
      "fuel_type_distribution": [
        {
          "fuel_type": "Gasoline",
          "count": 900,
          "percentage": 75
        },
        {
          "fuel_type": "Diesel",
          "count": 180,
          "percentage": 15
        }
      ],
      "year_distribution": [
        {
          "year": 2021,
          "count": 400,
          "percentage": 33.3
        },
        {
          "year": 2020,
          "count": 350,
          "percentage": 29.2
        }
      ]
    }
  }
}

⚠️ Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before retrying.",
    "details": {
      "limit": 100,
      "reset_time": "2024-01-15T11:00:00Z"
    }
  }
}

Common Error Codes

Error Codes

Code	HTTP Status	Description	Solution
INVALID_API_KEY	401	Invalid or expired API key	Check your API key in the dashboard
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded	Implement rate limiting and retry logic
INVALID_PARAMETERS	400	Invalid request parameters	Check parameter values and formats
PARSER_UNAVAILABLE	503	Parser temporarily unavailable	Retry after a few minutes
QUOTA_EXCEEDED	402	Monthly quota exceeded	Upgrade your plan or wait for reset
GEOGRAPHIC_RESTRICTION	403	Geographic restriction	Contact support for assistance
INVALID_MARKET	400	Invalid market parameter	Use valid market: us, ca, uk

📊 Rate Limits

Rate Limits by Plan

Plan	Requests per Minute	Monthly Quota	Concurrent Requests
Starter	100	50,000	5
Professional	500	250,000	20
Enterprise	2000	1,000,000	100

Rate Limit Headers

// Check rate limit headers
const response = await axios.post('/search', data, headers);

console.log('Remaining requests:', response.headers['x-ratelimit-remaining']);
console.log('Reset time:', response.headers['x-ratelimit-reset']);
console.log('Limit:', response.headers['x-ratelimit-limit']);

🔧 Code Examples

Complete JavaScript Example

const axios = require('axios');

class CarGurusAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.carapis.com/v1/parsers/cargurus';
    this.headers = {
      Authorization: `Bearer $\{apiKey\}`,
      'Content-Type': 'application/json',
    };
  }

  async searchVehicles(params) {
    try {
      const response = await axios.post(`${this.baseURL}/search`, params, { headers: this.headers });
      return response.data;
    } catch (error) {
      this.handleError(error);
    }
  }

  async getVehicleDetails(vehicleId) {
    try {
      const response = await axios.get(`${this.baseURL}/vehicle/$\{vehicleId\}`, { headers: this.headers });
      return response.data;
    } catch (error) {
      this.handleError(error);
    }
  }

  async getMarketStatistics(params = {}) {
    try {
      const response = await axios.get(`${this.baseURL}/statistics`, {
        params,
        headers: this.headers,
      });
      return response.data;
    } catch (error) {
      this.handleError(error);
    }
  }

  handleError(error) {
    if (error.response?.status === 429) {
      console.log('Rate limit exceeded. Please wait before retrying.');
    } else if (error.response?.status === 401) {
      console.log('Invalid API key. Please check your credentials.');
    } else {
      console.log('API Error:', error.response?.data || error.message);
    }
    throw error;
  }
}

// Usage
const api = new CarGurusAPI('YOUR_API_KEY');

// Search for vehicles in US market
const searchResult = await api.searchVehicles({
  query: 'Ford F-150',
  market: 'us',
  max_price: 50000,
  location: 'New York',
});

// Get vehicle details
const vehicleDetails = await api.getVehicleDetails('123456789');

// Get market statistics
const statistics = await api.getMarketStatistics({
  market: 'us',
  brand: 'Ford',
  location: 'New York',
});

Complete Python Example

import requests
import time
from typing import Dict, Optional

class CarGurusAPI:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://api.carapis.com/v1/parsers/cargurus'
        self.headers = {
            'Authorization': f'Bearer \{api_key\}',
            'Content-Type': 'application/json'
        }

    def search_vehicles(self, params: Dict) -> Optional[Dict]:
        try:
            response = requests.post(
                f'{self.base_url}/search',
                json=params,
                headers=self.headers
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            self.handle_error(e)
            return None

    def get_vehicle_details(self, vehicle_id: str) -> Optional[Dict]:
        try:
            response = requests.get(
                f'{self.base_url}/vehicle/\{vehicle_id\}',
                headers=self.headers
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            self.handle_error(e)
            return None

    def get_market_statistics(self, params: Dict = None) -> Optional[Dict]:
        try:
            response = requests.get(
                f'{self.base_url}/statistics',
                params=params or {},
                headers=self.headers
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            self.handle_error(e)
            return None

    def handle_error(self, error):
        if hasattr(error, 'response'):
            if error.response.status_code == 429:
                print('Rate limit exceeded. Please wait before retrying.')
            elif error.response.status_code == 401:
                print('Invalid API key. Please check your credentials.')
            else:
                print(f'API Error: {error.response.text}')
        else:
            print(f'Request Error: \{error\}')

# Usage
api = CarGurusAPI('YOUR_API_KEY')

# Search for vehicles in US market
search_result = api.search_vehicles({
    'query': 'Ford F-150',
    'market': 'us',
    'max_price': 50000,
    'location': 'New York'
})

# Get vehicle details
vehicle_details = api.get_vehicle_details('123456789')

# Get market statistics
statistics = api.get_market_statistics({
    'market': 'us',
    'brand': 'Ford',
    'location': 'New York'
})

🚀 Next Steps

Ready to Integrate?

1. Quick Start Guide - Get started in 5 minutes
2. Market Analysis - Multi-market insights
3. Features - See what's included
4. FAQ - Common questions and answers

Need Help?

• Support - Technical assistance
• Community - Connect with other users
• Examples - See live examples
• Documentation - Complete documentation

---

Ready to extract multi-market automotive data? Start with the CarGurus API today and unlock comprehensive market intelligence across US, Canada, and UK markets.

Get Started Now →