API Documentation

Complete reference for the Vehicle Finder API. All endpoints are under https://api.vehicle-finder.com/v1

Try it liveNo signup required for free endpoints

Authentication

Pass your API key in the X-API-Key header with every request.

curl -H "X-API-Key: vda_your_key_here" \
  https://api.vehicle-finder.com/v1/makes

Rate Limits

Rate limits are per-minute and per-month based on your plan. Check the response headers:

  • X-RateLimit-Limit — Requests per minute
  • X-RateLimit-Remaining — Remaining this minute
  • X-Monthly-Limit — Monthly quota
  • X-Monthly-Remaining — Remaining this month

Exceeding limits returns 429 Too Many Requests.

Vehicles

GET
/v1/makes

List all vehicle makes

GET
/v1/makes/{make}/models?year=

List models for a make (optional year filter)

GET
/v1/vehicles?year=&make=&model=

Look up a vehicle by year, make, and model

GET
/v1/vehicles/{id}

Get a vehicle by ID

GET
/v1/vin/{vin}

Decode a 17-character VIN

// VIN Decode Response
{
  "data": {
    "year": 2024, "make": "Toyota", "model": "Camry", "trim": "SE",
    "engine": "2.5L I4 DOHC 16V", "vehicle_id": 4521,
    "body_class": "Sedan/Saloon", "doors": 4,
    "drive_type": "FWD", "fuel_type": "Gasoline",
    "displacement_liters": 2.5, "cylinders": 4,
    "horsepower": 203.0, "transmission": "Automatic",
    "plant_country": "United States (USA)",
    "manufacturer": "Toyota Motor Manufacturing",
    "vehicle_type": "PASSENGER CAR"
  }
}

Oil Change

GET
/v1/vehicles/{id}/oil-change

Oil specs, filters, and drain bolt info

// Response
{
  "data": {
    "oil_specs": [{
      "viscosity": "0W-20",
      "oil_type": "Full Synthetic",
      "capacity_with_filter": "5.0",
      "capacity_without_filter": "4.6"
    }],
    "filters": [{ "brand": "Toyota", "part_number": "04152-YZZA1" }],
    "drain_bolt": { "socket_size_mm": "14", "torque_nm": "25" }
  }
}

Fluids

GET
/v1/vehicles/{id}/fluids

Transmission, brake, coolant, power steering, differential, and transfer case fluid specs

// Response
{
  "data": {
    "vehicle_id": 1,
    "year": 2024, "make": "Toyota", "model": "Camry",
    "transmission_fluid": { "fluid_type": "ATF WS", "capacity_quarts": 3.7 },
    "brake_fluid": { "dot_type": "DOT 3" },
    "coolant": { "coolant_type": "Long Life", "color": "Pink", "capacity_quarts": 6.4 },
    "power_steering_fluid": { "fluid_type": "ATF Dexron III" },
    "differential_fluids": [{ "position": "rear", "fluid_type": "75W-90" }],
    "transfer_case_fluid": null
  }
}

Parts

GET
/v1/vehicles/{id}/parts

Spark plugs, air filters, cabin filters, brake pads/rotors, wiper blades, battery, and tire specs

// Response
{
  "data": {
    "vehicle_id": 1,
    "spark_plug_spec": { "plug_type": "Iridium", "gap": "0.044", "quantity": 4 },
    "battery_spec": { "group_size": "35", "cca": 550 },
    "tire_spec": { "size": "215/55R17", "pressure_front_psi": 35, "pressure_rear_psi": 35 },
    "spark_plugs": [{ "brand": "NGK", "part_number": "ILKAR7B11", "is_oem": true }],
    "air_filters": [{ "brand": "Toyota", "part_number": "17801-YZZ02", "is_oem": true }],
    "brake_pads": [{ "brand": "Akebono", "part_number": "ACT1293", "position": "front" }],
    "wiper_blades": [{ "brand": "Bosch", "part_number": "26A", "position": "driver", "size_inches": 26 }],
    "batteries": [{ "brand": "Interstate", "part_number": "MTZ-35", "is_oem": false }]
  }
}

Maintenance

GET
/v1/vehicles/{id}/maintenance?mileage=

Maintenance schedule (optional mileage filter)

Recalls

GET
/v1/vehicles/{id}/recalls

NHTSA safety recalls

Diagnostics

GET
/v1/diagnostics/{dtc_code}

Look up a DTC code (e.g., P0301)

GET
/v1/vehicles/{id}/diagnostics/{code}

Vehicle-specific diagnostic with repair costs (Pro)

Technical Service Bulletins

GET
/v1/vehicles/{id}/tsb

Technical Service Bulletins (Pro)

Consumer Complaints

GET
/v1/vehicles/{id}/complaints?component=&limit=&offset=

NHTSA consumer complaints with crash, fire, and injury data (Pro)

GET
/v1/vehicles/{id}/common-problems

Top reported problems aggregated by component (Pro)

// Common Problems Response
{
  "data": [
    {
      "component": "ENGINE",
      "complaint_count": 47,
      "crash_count": 2,
      "fire_count": 1,
      "injury_count": 3,
      "death_count": 0,
      "sample_description": "Engine stalls intermittently while driving..."
    }
  ]
}

Torque Specs

GET
/v1/vehicles/{id}/torque-specs

Lug nut, drain bolt, and spark plug torque specifications

// Response
{
  "data": [
    { "component": "lug_nut", "torque_ft_lbs": 76, "torque_nm": 103.0, "notes": "Alloy wheels" },
    { "component": "drain_bolt", "torque_ft_lbs": 30, "torque_nm": 40.7, "notes": "Use new crush washer" },
    { "component": "spark_plug", "torque_ft_lbs": 18, "torque_nm": 24.4, "notes": "14mm thread, aluminum head" }
  ]
}

Towing & Payload

GET
/v1/vehicles/{id}/towing

Towing capacity, payload, curb weight, GVWR, and hitch class (trucks/SUVs)

// Response (2024 Ford F-150)
{
  "data": {
    "max_towing_lbs": 13000,
    "max_payload_lbs": 3325,
    "curb_weight_lbs": 4069,
    "gvwr_lbs": 7050,
    "tongue_weight_lbs": 1300,
    "hitch_class": "IV"
  }
}

Service Cost Estimates

GET
/v1/vehicles/{id}/service-costs?region=&service_type=

Estimated repair costs by region with parts and labor breakdowns (Pro)

Regions: national, northeast, southeast, midwest, southwest, west

// Response
{
  "data": [
    {
      "service_type": "oil_change_synthetic",
      "region": "west",
      "cost_low": 90,
      "cost_high": 190,
      "cost_average": 140,
      "labor_hours_low": 0.3,
      "labor_hours_high": 0.5,
      "parts_cost_low": 50,
      "parts_cost_high": 120
    }
  ]
}

Fuel Economy

GET
/v1/vehicles/{id}/fuel-economy

EPA fuel economy (MPG) ratings — city, highway, combined, annual fuel cost

GET
/v1/fuel-economy?year=&make=&model=

Search fuel economy by year/make/model (returns all trims and engines)

// Response
{
  "data": [{
    "year": 2024, "make": "Toyota", "model": "Camry",
    "city_mpg": 28, "highway_mpg": 39, "combined_mpg": 32,
    "annual_fuel_cost": 1750,
    "engine_displacement": 2.5, "cylinders": 4,
    "transmission": "Automatic (S8)", "drive": "FWD",
    "fuel_type": "Regular Gasoline"
  }]
}

Engine Specs

GET
/v1/vehicles/{id}/engine-specs

Detailed engine specifications — horsepower, torque, displacement, aspiration, valve config, and engine internals

// Response (2024 Ford F-150)
{
  "data": [
    {
      "engine_variant": "3.5L EcoBoost V6",
      "horsepower": 400, "horsepower_rpm": 6000,
      "torque_ft_lbs": 500, "torque_rpm": 3100,
      "displacement_liters": 3.5, "displacement_cc": 3496,
      "cylinders": 6, "cylinder_config": "V",
      "valve_count": 24, "valve_config": "DOHC",
      "fuel_system": "Direct Injection",
      "aspiration": "Twin-Turbo",
      "compression_ratio": "10.0:1",
      "engine_code": "Duratec",
      "block_material": "Aluminum", "head_material": "Aluminum"
    },
    {
      "engine_variant": "5.0L Coyote V8",
      "horsepower": 400, "horsepower_rpm": 6000,
      "torque_ft_lbs": 410, "torque_rpm": 4250,
      "displacement_liters": 5.0, "displacement_cc": 4951,
      "cylinders": 8, "cylinder_config": "V",
      "aspiration": "Naturally Aspirated"
    }
  ]
}

Safety Ratings

GET
/v1/vehicles/{id}/safety-ratings

NHTSA crash test safety ratings — overall, frontal, side, and rollover scores (1-5 stars)

// Response
{
  "data": {
    "overall_rating": 5,
    "frontal_crash_driver": 4,
    "frontal_crash_passenger": 5,
    "side_crash_driver": 5,
    "side_crash_passenger": 5,
    "rollover_rating": 4,
    "rollover_risk_pct": 12.6,
    "side_pole_rating": 5
  }
}

Warranty

GET
/v1/vehicles/{id}/warranty

Manufacturer warranty coverage — basic, powertrain, corrosion, roadside, and battery warranties

// Response
{
  "data": [
    { "warranty_type": "basic", "months": 36, "miles": 36000, "notes": "Bumper-to-bumper" },
    { "warranty_type": "powertrain", "months": 60, "miles": 60000, "notes": "Engine, transmission, drivetrain" },
    { "warranty_type": "corrosion", "months": 60, "miles": null, "notes": "Body rust-through" },
    { "warranty_type": "roadside", "months": 24, "miles": 25000, "notes": "24/7 roadside assistance" }
  ]
}

Maintenance Predictor

GET
/v1/vehicles/{id}/maintenance/predict?mileage=45000

Predict overdue, due now, and upcoming maintenance based on current mileage

// Response
{
  "data": {
    "vehicle_id": 4521,
    "current_mileage": 45000,
    "overdue": [],
    "due_now": [
      { "description": "Replace engine air filter", "mileage_interval": 45000,
        "status": "due_now", "due_at_miles": 45000, "miles_until_due": 0 }
    ],
    "upcoming": [
      { "description": "Replace spark plugs", "mileage_interval": 60000,
        "status": "upcoming", "due_at_miles": 60000, "miles_until_due": 15000 }
    ]
  }
}

Total Cost of Ownership

GET
/v1/vehicles/{id}/tco?annual_miles=12000&gas_price=3.50

5-year cost projection combining fuel, maintenance, depreciation, and insurance

// Response
{
  "data": {
    "vehicle_id": 4521,
    "year": 2024, "make": "Toyota", "model": "Camry",
    "annual_miles": 12000, "gas_price": 3.5,
    "breakdown": {
      "fuel_annual": 1312, "fuel_5yr": 6562,
      "maintenance_annual": 680, "maintenance_5yr": 3400,
      "depreciation_5yr": 8500,
      "insurance_annual_est": 1200, "insurance_5yr_est": 6000,
      "total_annual": 4892, "total_5yr": 24462
    }
  }
}

Towing Calculator

GET
/v1/vehicles/{id}/towing/calculator?cargo_weight=5000&passengers=2

Check if a vehicle can tow a given weight with safety warnings

// Response
{
  "data": {
    "max_towing_lbs": 13000,
    "max_payload_lbs": 3325,
    "cargo_weight": 5000,
    "tongue_weight_est": 600,
    "remaining_towing_capacity": 8000,
    "remaining_payload": 2425,
    "can_tow": true,
    "can_carry": true,
    "warnings": []
  }
}

Similar Vehicles

GET
/v1/vehicles/{id}/similar?year_range=2&limit=5

Find comparable vehicles by year, price, and class

// Response
{
  "data": [
    { "vehicle_id": 5102, "year": 2024, "make": "Honda", "model": "Accord",
      "msrp": 28500, "combined_mpg": 33 },
    { "vehicle_id": 5305, "year": 2024, "make": "Hyundai", "model": "Sonata",
      "msrp": 27500, "combined_mpg": 32 }
  ]
}

Emissions

GET
/v1/vehicles/{id}/emissions

CO2 emissions per mile and per year, smog and greenhouse gas ratings

// Response
{
  "data": {
    "vehicle_id": 4521,
    "co2_grams_per_mile": 277.7,
    "co2_tons_per_year": 3.33,
    "smog_rating": 7,
    "greenhouse_rating": 7,
    "fuel_type": "Regular Gasoline",
    "combined_mpg": 32.0,
    "is_zero_emission": false
  }
}

Vehicle Images

GET
/v1/vehicles/{id}/images?angle=front&color=white

Vehicle photos filtered by angle (front, rear, side, interior) and color

// Response
{
  "data": [
    {
      "url": "https://example.com/2024-camry-front-white.jpg",
      "angle": "front",
      "color": "Super White",
      "width": 1920,
      "height": 1080,
      "source": "manufacturer",
      "license_type": "editorial"
    }
  ]
}

Reliability Scores

GET
/v1/vehicles/{id}/reliability

Reliability score (0-100) based on NHTSA complaint data with severity breakdown

// Response
{
  "data": {
    "overall_score": 72.3,
    "rating": "Good",
    "complaint_count": 245,
    "crash_count": 12,
    "fire_count": 3,
    "injury_count": 8,
    "death_count": 0,
    "severity_score": 418.0,
    "top_issue": "ENGINE"
  }
}

Vehicle Valuation

GET
/v1/vehicles/{id}/valuation

Estimated vehicle values — trade-in, private party, and retail — with MSRP and depreciation

// Response
{
  "data": {
    "msrp": 30000,
    "trade_in_low": 14025,
    "trade_in_high": 15675,
    "private_party_low": 15675,
    "private_party_high": 17325,
    "retail_low": 18150,
    "retail_high": 20625,
    "depreciation_pct": 46.0,
    "condition_notes": "Estimated values assume average condition and mileage for vehicle age."
  }
}

Paint Codes

GET
/v1/vehicles/{id}/paint-codes

OEM paint codes, color names, color groups, types, hex values, and touch-up part numbers

// Response
{
  "data": [
    {
      "color_name": "Super White",
      "paint_code": "040",
      "color_group": "White",
      "paint_type": "Solid",
      "hex_color": "#FFFFFF",
      "touch_up_part_number": null
    },
    {
      "color_name": "Midnight Black Metallic",
      "paint_code": "218",
      "color_group": "Black",
      "paint_type": "Metallic",
      "hex_color": "#0D0D0D",
      "touch_up_part_number": null
    }
  ]
}

Code Examples

Python

import requests

headers = {"X-API-Key": "vda_your_key_here"}
r = requests.get(
    "https://api.vehicle-finder.com/v1/vehicles",
    params={"year": 2024, "make": "Toyota", "model": "Camry"},
    headers=headers,
)
vehicle = r.json()["data"]

JavaScript

const res = await fetch(
  "https://api.vehicle-finder.com/v1/vehicles?year=2024&make=Toyota&model=Camry",
  { headers: { "X-API-Key": "vda_your_key_here" } }
);
const { data } = await res.json();