🔌 Vroom API Reference

Complete endpoint documentation for extracting real-time automotive data from America's innovative car marketplace

API Overview

Base URL: https://api.carapis.com/v1/parsers/vroom
Authentication: Bearer token required
Rate Limits: 1,000 requests/day (free), 10,000 requests/day (pro)
Response Format: JSON
Timezone: America/New_York (UTC-5)

🔑 Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer vroom_parser_sk_your_api_key_here

API Key Format

Your Vroom API key follows this pattern: vroom_parser_sk_ followed by a 32-character hexadecimal string.

📡 Endpoints

Search Vehicles

Search for vehicles with various filters and parameters.

Endpoint: GET /search

Parameters:

Parameter	Type	Required	Description	Example
`make`	string	No	Vehicle brand	"Toyota", "Honda"
`model`	string	No	Vehicle model	"Camry", "Accord"
`state`	string	No	US state	"California", "Texas"
`year_min`	integer	No	Minimum year	2020
`year_max`	integer	No	Maximum year	2024
`price_min`	integer	No	Minimum price (USD)	20000
`price_max`	integer	No	Maximum price (USD)	50000
`fuel_type`	string	No	Fuel type	"Gasoline", "Hybrid"
`transmission`	string	No	Transmission	"Automatic", "Manual"
`quality_rating`	string	No	Quality rating	"excellent", "good", "fair"
`body_type`	string	No	Body type	"Sedan", "SUV", "Truck"
`limit`	integer	No	Results per page (max 100)	25
`page`	integer	No	Page number	1

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/vroom/search" \
  -H "Authorization: Bearer vroom_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -G \
  -d "make=Toyota" \
  -d "state=California" \
  -d "year_min=2020" \
  -d "limit=10"

Example Response:

{
  "success": true,
  "data": {
    "vehicles": [
      {
        "id": "vroom_12345",
        "title": "2021 Toyota Camry LE",
        "price": {
          "current": 25000,
          "currency": "USD",
          "negotiable": false,
          "delivery_cost": 0
        },
        "specifications": {
          "make": "Toyota",
          "model": "Camry",
          "year": 2021,
          "trim": "LE",
          "engine": "2.5L 4-Cylinder",
          "transmission": "Automatic",
          "mileage": 25000,
          "fuel_type": "Gasoline",
          "body_type": "Sedan"
        },
        "quality_assurance": {
          "inspection_score": 95,
          "quality_rating": "excellent"
        },
        "location": {
          "state": "California",
          "city": "Los Angeles",
          "dealer_name": "Vroom Los Angeles"
        },
        "url": "https://www.vroom.com/cars/toyota-camry-2021",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total_results": 1250,
    "page": 1,
    "limit": 10
  }
}

Get Vehicle Details

Retrieve detailed information about a specific vehicle.

Endpoint: GET /vehicle/\{vehicle_id\}

Parameters:

Parameter	Type	Required	Description
`vehicle_id`	string	Yes	Unique vehicle identifier

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/vroom/vehicle/12345" \
  -H "Authorization: Bearer vroom_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "vehicle": {
      "id": "vroom_12345",
      "title": "2021 Toyota Camry LE",
      "price": {
        "current": 25000,
        "currency": "USD",
        "negotiable": false,
        "delivery_cost": 0,
        "financing_available": true
      },
      "specifications": {
        "make": "Toyota",
        "model": "Camry",
        "year": 2021,
        "trim": "LE",
        "engine": "2.5L 4-Cylinder",
        "transmission": "Automatic",
        "mileage": 25000,
        "fuel_type": "Gasoline",
        "body_type": "Sedan",
        "color": "White",
        "seats": 5,
        "doors": 4
      },
      "quality_assurance": {
        "inspection_score": 95,
        "quality_rating": "excellent",
        "inspection_date": "2024-01-15",
        "warranty_months": 12,
        "service_history": "complete",
        "inspection_report": {
          "engine_performance": "excellent",
          "exterior_condition": "excellent",
          "interior_condition": "excellent",
          "safety_features": "excellent"
        }
      },
      "location": {
        "state": "California",
        "city": "Los Angeles",
        "dealer_name": "Vroom Los Angeles",
        "dealer_address": "123 Main St, Los Angeles, CA",
        "delivery_available": true,
        "delivery_cost": 0
      },
      "features": ["Bluetooth", "Backup Camera", "Apple CarPlay", "Android Auto", "Lane Departure Warning", "Automatic Emergency Braking"],
      "financing": {
        "available": true,
        "partners": ["Vroom Finance", "Third-party lenders"],
        "interest_rate": "5.9%",
        "tenure_options": [36, 48, 60, 72]
      },
      "url": "https://www.vroom.com/cars/toyota-camry-2021",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:15:00Z"
    }
  }
}

Get Makes

Retrieve list of available vehicle makes.

Endpoint: GET /makes

Parameters: None

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/vroom/makes" \
  -H "Authorization: Bearer vroom_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "makes": [
      {
        "name": "Toyota",
        "count": 15420,
        "popular_models": ["Camry", "Corolla", "RAV4"]
      },
      {
        "name": "Honda",
        "count": 12850,
        "popular_models": ["Accord", "Civic", "CR-V"]
      },
      {
        "name": "Ford",
        "count": 8250,
        "popular_models": ["F-150", "Escape", "Explorer"]
      },
      {
        "name": "Chevrolet",
        "count": 6250,
        "popular_models": ["Silverado", "Equinox", "Malibu"]
      }
    ]
  }
}

Get Models

Retrieve models for a specific make.

Endpoint: GET /makes/\{make\}/models

Parameters:

Parameter	Type	Required	Description
`make`	string	Yes	Make name (e.g., "Toyota")

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/vroom/makes/Toyota/models" \
  -H "Authorization: Bearer vroom_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "make": "Toyota",
    "models": [
      {
        "name": "Camry",
        "count": 3250,
        "years": [2020, 2021, 2022, 2023, 2024]
      },
      {
        "name": "Corolla",
        "count": 2800,
        "years": [2020, 2021, 2022, 2023, 2024]
      },
      {
        "name": "RAV4",
        "count": 1850,
        "years": [2020, 2021, 2022, 2023, 2024]
      }
    ]
  }
}

Get States

Retrieve list of available US states.

Endpoint: GET /states

Parameters: None

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/vroom/states" \
  -H "Authorization: Bearer vroom_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "states": [
      {
        "name": "California",
        "abbreviation": "CA",
        "count": 8500,
        "region": "West Coast"
      },
      {
        "name": "Texas",
        "abbreviation": "TX",
        "count": 6800,
        "region": "Southwest"
      },
      {
        "name": "Florida",
        "abbreviation": "FL",
        "count": 6200,
        "region": "Southeast"
      },
      {
        "name": "New York",
        "abbreviation": "NY",
        "count": 5800,
        "region": "Northeast"
      }
    ]
  }
}

Get Market Statistics

Retrieve market statistics and trends.

Endpoint: GET /statistics

Parameters:

Parameter	Type	Required	Description	Example
`make`	string	No	Filter by make	"Toyota"
`state`	string	No	Filter by state	"California"
`period`	string	No	Time period	"30d", "90d", "1y"

Example Request:

curl -X GET "https://api.carapis.com/v1/parsers/vroom/statistics?make=Toyota&state=California&period=30d" \
  -H "Authorization: Bearer vroom_parser_sk_your_api_key_here" \
  -H "Content-Type: application/json"

Example Response:

{
  "success": true,
  "data": {
    "statistics": {
      "total_listings": 15420,
      "average_price": 35000,
      "price_range": {
        "min": 15000,
        "max": 80000
      },
      "quality_distribution": {
        "excellent": 45.2,
        "good": 38.8,
        "fair": 16.0
      },
      "popular_models": [
        {
          "name": "Camry",
          "count": 3250,
          "avg_price": 28000
        },
        {
          "name": "Corolla",
          "count": 2800,
          "avg_price": 22000
        }
      ],
      "price_trends": [
        {
          "date": "2024-01-01",
          "avg_price": 34500,
          "listings": 15200
        },
        {
          "date": "2024-01-15",
          "avg_price": 35000,
          "listings": 15420
        }
      ]
    }
  }
}

📊 Response Codes

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

🔧 Error Responses

Authentication Error

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key",
    "details": "The provided API key is invalid or expired"
  }
}

Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters",
    "details": {
      "price_min": "Must be a positive integer",
      "year_max": "Must be between 1990 and 2024"
    }
  }
}

Rate Limit Error

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "reset_time": "2024-01-21T00:00:00Z"
    }
  }
}

🚨 Rate Limits

Rate Limit Information

Free Plan: 1,000 requests per day
Pro Plan: 10,000 requests per day
Enterprise: Custom limits available
Reset Time: Daily at 00:00 UTC

Rate Limit Headers

The API includes rate limit information in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1705795200

📝 Code Examples

Python SDK

import requests
from typing import Dict, List, Optional

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

    def search_vehicles(self, **params) -> Dict:
        """Search for vehicles with filters"""
        response = requests.get(f"{self.base_url}/search",
                              headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_vehicle(self, vehicle_id: str) -> Dict:
        """Get detailed vehicle information"""
        response = requests.get(f"{self.base_url}/vehicle/\{vehicle_id\}",
                              headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_makes(self) -> Dict:
        """Get available makes"""
        response = requests.get(f"{self.base_url}/makes",
                              headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_models(self, make: str) -> Dict:
        """Get models for a specific make"""
        response = requests.get(f"{self.base_url}/makes/\{make\}/models",
                              headers=self.headers)
        response.raise_for_status()
        return response.json()

# Usage
api = VroomAPI("vroom_parser_sk_your_api_key_here")

# Search for Toyota cars
results = api.search_vehicles(make="Toyota", state="California", limit=10)

# Get vehicle details
vehicle = api.get_vehicle("12345")

JavaScript SDK

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

  async searchVehicles(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const response = await fetch(`${this.baseUrl}/search?$\{queryString\}`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }

  async getVehicle(vehicleId) {
    const response = await fetch(`${this.baseUrl}/vehicle/$\{vehicleId\}`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }

  async getMakes() {
    const response = await fetch(`${this.baseUrl}/makes`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }

  async getModels(make) {
    const response = await fetch(`${this.baseUrl}/makes/$\{make\}/models`, {
      method: 'GET',
      headers: this.headers,
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  }
}

// Usage
const api = new VroomAPI('vroom_parser_sk_your_api_key_here');

// Search for Honda cars
api
  .searchVehicles({ make: 'Honda', state: 'Texas', limit: 10 })
  .then((results) => console.log(results))
  .catch((error) => console.error(error));

// Get vehicle details
api
  .getVehicle('12345')
  .then((vehicle) => console.log(vehicle))
  .catch((error) => console.error(error));

🔄 Webhooks

Webhook Support

Webhooks are available for real-time data updates. Contact our support team to set up webhook notifications for new listings and price changes.

Webhook Events

Event	Description
`vehicle.created`	New vehicle listing added
`vehicle.updated`	Vehicle information updated
`vehicle.removed`	Vehicle listing removed
`price.changed`	Vehicle price changed
`quality.updated`	Quality inspection updated

Webhook Payload

{
  "event": "vehicle.created",
  "timestamp": "2024-01-20T14:30:00Z",
  "data": {
    "vehicle_id": "12345",
    "title": "2021 Toyota Camry LE",
    "price": 25000,
    "state": "California",
    "quality_rating": "excellent"
  }
}

📞 Support

Need Help?

API Status - Check API availability
Documentation - Complete documentation
Support - Contact our team
Community - Developer community

Ready to start? Get your API key and begin extracting Vroom data today!

🔑 Authentication​

📡 Endpoints​

Search Vehicles​

Get Vehicle Details​

Get Makes​

Get Models​

Get States​

Get Market Statistics​

📊 Response Codes​

🔧 Error Responses​

Authentication Error​

Validation Error​

Rate Limit Error​

🚨 Rate Limits​

Rate Limit Headers​

📝 Code Examples​

Python SDK​

JavaScript SDK​

🔄 Webhooks​

Webhook Events​

Webhook Payload​

📞 Support​

🔑 Authentication

📡 Endpoints

Search Vehicles

Get Vehicle Details

Get Makes

Get Models

Get States

Get Market Statistics

📊 Response Codes

🔧 Error Responses

Authentication Error

Validation Error

Rate Limit Error

🚨 Rate Limits

Rate Limit Headers

📝 Code Examples

Python SDK

JavaScript SDK

🔄 Webhooks

Webhook Events

Webhook Payload

📞 Support