Get Stats

Get statistical information about auctions including price trends and sell-through rates. Requires a paid plan (not available on free accounts).

GET https://api.oldcarsdata.com/stats

Authentication

This endpoint requires authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Paid Plan Required: This endpoint is not available on the free (Starter) plan. Upgrade to a paid plan to access statistical data and price trends.

Request Parameters

Field	Type	Required	Description
`Authorization`	header	Yes	Bearer token with your API key: `Bearer YOUR_API_KEY`
`make`	string	Yes	Make name (e.g., "Toyota"). Minimum length: 1 character.
`model`	string	No	Model name to filter statistics by
`year_min`	integer	No	Minimum year filter (inclusive)
`year_max`	integer	No	Maximum year filter (inclusive)

Code Examples

cURL

bash

curl "https://api.oldcarsdata.com/stats?make=Toyota&model=Land+Cruiser" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

javascript

const response = await fetch(
  'https://api.oldcarsdata.com/stats?make=Toyota&model=Land+Cruiser',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();

Python

python

import requests

response = requests.get(
    'https://api.oldcarsdata.com/stats',
    params={'make': 'Toyota', 'model': 'Land Cruiser'},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

Success Response (200)

Stats retrieved successfully.

json

{
  "total_sales": 150,
  "average_price": 42500,
  "median_price": 40000,
  "lowest_price": 15000,
  "highest_price": 125000,
  "sell_through_rate": 0.75,
  "price_trend": [
    {
      "date": "2024-01",
      "avg_price": 41000,
      "volume": 12
    },
    {
      "date": "2024-02",
      "avg_price": 43000,
      "volume": 15
    }
  ]
}

Response Fields

Field	Type	Description
`total_sales`	number	Total number of sold auctions matching the filters
`average_price`	number	Average sale price (rounded to nearest integer)
`median_price`	number	Median sale price (rounded to nearest integer)
`lowest_price`	number	Lowest sale price
`highest_price`	number	Highest sale price
`sell_through_rate`	number	Sell-through rate as a decimal (0.0 to 1.0)
`price_trend`	array	Monthly price trend data for the last 12 months
`price_trend[].date`	string	Month in YYYY-MM format
`price_trend[].avg_price`	number	Average price for that month (rounded)
`price_trend[].volume`	number	Number of sales in that month

Error Responses

Field	Type	Description
`error`	string	Error type identifier
`message`	string	Human-readable error message
`details`	object	Validation error details (400 responses only)

403 — Forbidden:

json

{
  "error": "Forbidden",
  "message": "The stats endpoint is not available on the free plan. Please upgrade to access this feature."
}

401 — Unauthorized:

json

{
  "error": "Unauthorized",
  "message": "API key is required. Provide it via Authorization: Bearer <key> header"
}