Skip to main content

CarGurus Parser FAQ

Frequently asked questions about extracting multi-market automotive data from CarGurus. Get answers to setup, usage, troubleshooting, and technical questions for US, Canada, and UK markets.

Quick Navigation

Setup & Configuration​

How do I get started with the CarGurus parser?​

Getting Started
  1. Sign up for a Carapis account at dashboard.carapis.com
  2. Activate the CarGurus parser in your dashboard
  3. Get your API key from the parser settings
  4. Choose your target markets (US, Canada, UK)
  5. Make your first request using our Quick Start Guide

What API key format should I expect?​

API Key Format

Your CarGurus parser API key will look like this: cargurus_parser_sk_1234567890abcdef1234567890abcdef

The key starts with cargurus_parser_sk_ followed by a 32-character hexadecimal string.

How do I authenticate my API requests?​

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

What programming languages are supported?​

Supported Languages
  • JavaScript/Node.js - Full support with axios/fetch
  • Python - Full support with requests library
  • cURL - Command-line interface
  • PHP - With curl or Guzzle
  • Java - With OkHttp or Apache HttpClient
  • C# - With HttpClient
  • Go - With net/http package
  • Ruby - With Net::HTTP

Multi-Market Usage​

What markets does the CarGurus parser support?​

Supported Markets
MarketCodeCoverageCurrencyKey Features
United Statesus2M+ vehiclesUSDDeal Rating, EPA ratings
Canadaca500K+ vehiclesCADProvincial data, bilingual
United Kingdomuk500K+ vehiclesGBPMOT data, UK standards

Can I search across multiple markets simultaneously?​

Multi-Market Search

Currently, you need to make separate API calls for each market. This ensures:

  • Market-specific data - Accurate results for each region
  • Local pricing - Currency and market-specific pricing
  • Regional filters - Location-specific search parameters
  • Compliance - Market-specific regulatory requirements

How do I specify the target market in my requests?​

// US market search
const usSearch = {
  query: 'Ford F-150',
  market: 'us',
  location: 'New York',
  max_price: 50000,
};

// Canada market search
const caSearch = {
  query: 'Toyota Camry',
  market: 'ca',
  location: 'Toronto',
  max_price: 45000,
};

// UK market search
const ukSearch = {
  query: 'BMW 3 Series',
  market: 'uk',
  location: 'London',
  max_price: 35000,
};

Are there market-specific parameters I should know about?​

Market-Specific Parameters
MarketSpecial ParametersDescription
USepa_rating, us_standardsEPA fuel economy ratings
Canadaprovince, bilingualProvincial data, French support
UKmot_status, uk_standardsMOT certification, UK regulations

Deal Rating Analysis​

What is the CarGurus Deal Rating?​

Deal Rating Explanation

The CarGurus Deal Rating is a proprietary algorithm that evaluates vehicle pricing against market conditions:

  • Score Range: 1.0-10.0
  • Categories: Great Deal (9.0-10.0), Good Deal (7.0-8.9), Fair Deal (5.0-6.9), High Price (1.0-4.9)
  • Market Comparison: Compares price to similar vehicles in the area
  • Real-time Updates: Updates as market conditions change
  • Proprietary Algorithm: CarGurus' unique evaluation system

How accurate are the deal ratings?​

Deal Rating Accuracy
  • Market-based: Uses real market data for comparison
  • Regional factors: Considers local market conditions
  • Vehicle-specific: Accounts for make, model, year, mileage
  • Time-sensitive: Updates with market changes
  • Statistical basis: Uses large datasets for accuracy

Can I filter by deal rating in my searches?​

// Search for great deals only
const greatDealsSearch = {
  query: 'Ford F-150',
  market: 'us',
  min_deal_rating: 9.0, // Great deals only
  max_price: 50000,
};

// Search for vehicles with good or better deals
const goodDealsSearch = {
  query: 'Toyota Camry',
  market: 'us',
  min_deal_rating: 7.0, // Good deals and better
  location: 'Los Angeles',
};

How do deal ratings vary by market?​

Deal Rating Market Variations
MarketAverage Deal RatingGreat Deals %Key Factors
United States7.215%High competition, transparent pricing
Canada7.012%Moderate competition, regional variations
United Kingdom7.418%More price variation, good opportunities

Data & Features​

What data can I extract from CarGurus?​

Available Data Fields
CategoryData PointsExamples
Vehicle InformationBrand, model, year, price, mileageFord F-150, 2020, $42,000, 35,000 miles
Deal RatingScore, label, explanation9.2, "Great Deal", pricing analysis
Technical SpecificationsEngine, transmission, fuel economy3.5L V6, Automatic, 22 mpg
Location DataCity, state, country, coordinatesNew York, NY, United States
Seller InformationDealer name, rating, contact detailsNYC Ford Dealership, 4.7/5.0
Features & OptionsEquipment packages, technologyNavigation, Leather Seats
Market IntelligencePrice trends, market statisticsAverage prices, demand patterns

How fresh is the data?​

Data Freshness
  • Real-time extraction - Data is extracted live from CarGurus
  • Sub-5 minute updates - New listings appear within 5 minutes
  • Price updates - Price changes reflected immediately
  • Deal rating updates - Ratings update with market changes
  • Inventory changes - Vehicle availability updated in real-time

Can I get historical price data?​

Historical Data
  • Price history - Track price changes over time
  • Market trends - Historical market analysis
  • Deal rating trends - How deal ratings change over time
  • Seasonal patterns - Year-over-year comparisons
  • Brand performance - Historical brand analysis

Do you support webhooks for real-time updates?​

Webhook Support
  • Real-time notifications - Instant updates when new vehicles are listed
  • Custom endpoints - Send data to your own servers
  • Event filtering - Filter notifications by criteria
  • Retry logic - Automatic retry for failed deliveries
  • Security - Signed webhook payloads for verification

Technical Issues​

What are the rate limits for the CarGurus parser?​

Rate Limits by Plan
PlanRequests per MinuteMonthly QuotaConcurrent Requests
Starter10050,0005
Professional500250,00020
Enterprise20001,000,000100

Implement proper rate limiting to avoid hitting limits.

How do I handle rate limit errors?​

// JavaScript - Rate limit handling
const handleRateLimit = async (requestFunction) => {
  try {
    return await requestFunction();
  } catch (error) {
    if (error.response?.status === 429) {
      const resetTime = error.response.headers['x-ratelimit-reset'];
      const waitTime = new Date(resetTime) - new Date();

      console.log(`Rate limit exceeded. Waiting ${waitTime}ms`);
      await new Promise((resolve) => setTimeout(resolve, waitTime));

      return await requestFunction(); // Retry
    }
    throw error;
  }
};

What should I do if I get a 401 Unauthorized error?​

Authentication Issues
  1. Check your API key - Verify it's correct and active
  2. Verify parser activation - Ensure CarGurus parser is activated in dashboard
  3. Check key format - Should start with cargurus_parser_sk_
  4. Contact support - If issues persist, contact our support team
  5. Check account status - Ensure your account is active and not suspended

How do I handle API errors properly?​

# Python - Error handling
import requests

def handle_api_request(url, data, headers):
    try:
        response = requests.post(url, json=data, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Authentication error - check your API key")
        elif e.response.status_code == 429:
            print("Rate limit exceeded - implement retry logic")
        elif e.response.status_code == 400:
            print("Invalid request parameters")
        else:
            print(f"HTTP Error: {e.response.status_code}")
    except requests.exceptions.RequestException as e:
        print(f"Request Error: {e}")
    return None

Why am I not getting any search results?​

Common Causes
IssueCauseSolution
No resultsSearch too specificBroaden search criteria
Wrong marketInvalid market parameterUse valid market: us, ca, uk
Wrong locationInvalid city/state nameUse correct location names
Price too lowBelow market rangeIncrease minimum price
Year too newNo vehicles in rangeAdjust year range
Fuel type mismatchLimited availabilityTry different fuel types

Business & Pricing​

How much does the CarGurus parser cost?​

Pricing Plans
PlanMonthly CostRequests/MonthFeatures
Starter$9950,000Basic search and extraction
Professional$299250,000Advanced filters, market data
Enterprise$9991,000,000Custom solutions, priority support

Contact us for custom enterprise pricing.

Can I get a free trial?​

Free Trial
  • 7-day free trial available for all plans
  • No credit card required for trial
  • Full API access during trial period
  • 10,000 free requests to test the service
  • Multi-market access - Test US, Canada, UK markets
  • Easy upgrade to paid plan when ready

What's included in each plan?​

Plan Comparison
FeatureStarterProfessionalEnterprise
Search API✅✅✅
Vehicle Details✅✅✅
Deal Rating Data✅✅✅
Market Statistics❌✅✅
Historical Data❌✅✅
Webhook Support❌✅✅
Multi-market Access✅✅✅
Priority Support❌❌✅
Custom Solutions❌❌✅

Do you offer volume discounts?​

Volume Discounts
  • Annual billing - 20% discount on all plans
  • High-volume usage - Custom pricing for 1M+ requests/month
  • Enterprise customers - Negotiated rates for large deployments
  • Reseller program - Special pricing for partners and resellers

Can I cancel my subscription anytime?​

Flexible Billing
  • No long-term contracts - Cancel anytime
  • Pro-rated refunds - Unused portion refunded
  • Data retention - Access to historical data for 30 days
  • Easy reactivation - Resume service anytime

Legal & Compliance​

Legal Compliance
  • CCPA compliant - Full compliance with US data protection laws
  • GDPR compliant - European data protection regulations
  • Terms of service - Compliant with CarGurus terms
  • Ethical extraction - Respectful data collection practices
  • Rate limiting - Responsible usage to avoid server overload
  • Legal consultation - We recommend consulting with legal counsel for your specific use case

How do you handle data protection laws?​

Data Protection Compliance
  • Data minimization - Only collect necessary data
  • User consent - Respect user privacy preferences
  • Data retention - Limited retention periods
  • Right to deletion - Honor deletion requests
  • Data security - Encrypted data transmission and storage
  • Audit trails - Complete activity logging for compliance

Can I use the data for commercial purposes?​

Commercial Usage
  • Business applications - Yes, for legitimate business purposes
  • Market research - Yes, for industry analysis and insights
  • Competitive intelligence - Yes, for market positioning
  • Resale restrictions - Data cannot be resold without permission
  • Attribution required - Credit Carapis as data source

What are the usage restrictions?​

Usage Restrictions
  • No resale - Cannot resell data without explicit permission
  • No scraping - Cannot use data to build competing services
  • Rate limiting - Must respect rate limits and fair use policies
  • Attribution - Must credit Carapis as data source
  • Legal compliance - Must comply with all applicable laws

Advanced Features​

Can I get market statistics and analytics?​

Market Intelligence
  • Price trends - Average prices and market movements
  • Brand performance - Market share and popularity metrics
  • Regional analysis - Geographic market insights
  • Demand patterns - Seasonal and trend analysis
  • Competitive intelligence - Dealer network analysis

Do you offer custom data extraction?​

Custom Solutions
  • Custom fields - Extract specific data points
  • Bulk extraction - Large-scale data collection
  • Scheduled extraction - Automated data collection
  • Data transformation - Custom data formatting
  • Integration support - Direct database integration

Can I integrate with my existing systems?​

Integration Support
  • RESTful API - Standard HTTP methods and JSON responses
  • SDK libraries - Official libraries for popular languages
  • Webhook integration - Real-time data delivery
  • Database integration - Direct database connections
  • Custom solutions - Tailored integration support

Support & Documentation​

How do I get technical support?​

Support Options
  • Documentation - Complete guides and examples
  • API Reference - Detailed endpoint documentation
  • Community Forum - Connect with other users
  • Email Support - Technical assistance via email
  • Priority Support - Dedicated support for enterprise customers

Where can I find code examples?​

Code Examples

Do you provide integration assistance?​

Integration Support
  • Setup assistance - Help with initial configuration
  • Code review - Review your integration code
  • Best practices - Guidance on optimal implementation
  • Performance optimization - Help optimize your usage
  • Custom solutions - Tailored integration support

Still have questions? Contact our support team for personalized assistance.

Contact Support →