{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/marketcheck/json-schema/marketcheck-search-response-schema.json",
  "title": "SearchResponse",
  "description": "Response object from search API",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/marketcheck-listings-api-openapi.yml#/components/schemas/SearchResponse",
  "type": "object",
  "properties": {
    "num_found": {
      "type": "integer",
      "description": "Total number of listings found"
    },
    "listings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Listing"
      }
    },
    "stats": {
      "type": "object",
      "description": "Statistics for the search results",
      "additionalProperties": true
    },
    "facets": {
      "type": "object",
      "description": "Facets for the search results",
      "additionalProperties": true
    }
  },
  "$defs": {
    "BaseListing": {
      "type": "object",
      "description": "Base listing object containing minimal car listing information",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique listing identifier"
        },
        "vin": {
          "type": "string",
          "description": "Vehicle Identification Number"
        },
        "heading": {
          "type": "string",
          "description": "Listing heading / title"
        },
        "price": {
          "type": "number",
          "description": "Listed price in USD"
        },
        "miles": {
          "type": "integer",
          "description": "Odometer reading in miles"
        },
        "msrp": {
          "type": "number",
          "description": "Manufacturer Suggested Retail Price"
        },
        "data_source": {
          "type": "string",
          "description": "Source of the listing data"
        },
        "source_url": {
          "type": "string",
          "description": "URL to the original listing source"
        },
        "seller_type": {
          "type": "string",
          "description": "Type of seller: dealer, private, auction",
          "enum": [
            "dealer",
            "private",
            "auction"
          ]
        },
        "car_type": {
          "type": "string",
          "description": "Type of car listing",
          "enum": [
            "new",
            "used",
            "certified"
          ]
        },
        "scraped_at": {
          "type": "integer",
          "description": "Unix timestamp when the listing was scraped"
        },
        "last_seen_at": {
          "type": "integer",
          "description": "Unix timestamp when the listing was last seen"
        },
        "first_seen_at": {
          "type": "integer",
          "description": "Unix timestamp when the listing was first seen"
        },
        "dom": {
          "type": "integer",
          "description": "Days on market"
        },
        "dom_180": {
          "type": "integer",
          "description": "Days on market in the last 180 days"
        },
        "dom_active": {
          "type": "integer",
          "description": "Active days on market"
        },
        "dealer_id": {
          "type": "string",
          "description": "Dealer identifier"
        },
        "ref_price": {
          "type": "number",
          "description": "Reference/comparison price"
        },
        "ref_miles": {
          "type": "number",
          "description": "Reference/comparison miles"
        },
        "ref_year": {
          "type": "integer",
          "description": "Reference year"
        },
        "build": {
          "$ref": "#/$defs/Build"
        },
        "dealer": {
          "$ref": "#/$defs/Dealer"
        }
      }
    },
    "Build": {
      "type": "object",
      "description": "Vehicle build/specification information decoded from VIN",
      "properties": {
        "year": {
          "type": "integer",
          "description": "Model year"
        },
        "make": {
          "type": "string",
          "description": "Vehicle make"
        },
        "model": {
          "type": "string",
          "description": "Vehicle model"
        },
        "trim": {
          "type": "string",
          "description": "Vehicle trim level"
        },
        "body_type": {
          "type": "string",
          "description": "Body type (sedan, SUV, truck, etc.)"
        },
        "vehicle_type": {
          "type": "string",
          "description": "Vehicle type classification"
        },
        "transmission": {
          "type": "string",
          "description": "Transmission type"
        },
        "drivetrain": {
          "type": "string",
          "description": "Drivetrain type (FWD, AWD, RWD, 4WD)"
        },
        "fuel_type": {
          "type": "string",
          "description": "Fuel type"
        },
        "engine": {
          "type": "string",
          "description": "Engine description"
        },
        "engine_size": {
          "type": "string",
          "description": "Engine displacement"
        },
        "cylinders": {
          "type": "integer",
          "description": "Number of cylinders"
        },
        "doors": {
          "type": "integer",
          "description": "Number of doors"
        },
        "made_in": {
          "type": "string",
          "description": "Country of manufacture"
        },
        "highway_fuel_economy": {
          "type": "integer",
          "description": "Highway fuel economy in MPG"
        },
        "city_fuel_economy": {
          "type": "integer",
          "description": "City fuel economy in MPG"
        }
      }
    },
    "Dealer": {
      "type": "object",
      "description": "Dealer information",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique dealer identifier"
        },
        "name": {
          "type": "string",
          "description": "Dealer name"
        },
        "website": {
          "type": "string",
          "description": "Dealer website URL"
        },
        "dealer_type": {
          "type": "string",
          "description": "Type of dealership"
        },
        "zip": {
          "type": "string",
          "description": "Dealer zip code"
        },
        "city": {
          "type": "string",
          "description": "Dealer city"
        },
        "state": {
          "type": "string",
          "description": "Dealer state"
        },
        "latitude": {
          "type": "number",
          "description": "Dealer latitude"
        },
        "longitude": {
          "type": "number",
          "description": "Dealer longitude"
        },
        "phone": {
          "type": "string",
          "description": "Dealer phone number"
        },
        "franchises": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of car franchises/makes the dealer carries"
        }
      }
    },
    "Listing": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseListing"
        }
      ],
      "type": "object",
      "description": "Full listing object with all attributes",
      "properties": {
        "vdp_url": {
          "type": "string",
          "description": "URL to the Vehicle Details Page"
        },
        "stock_no": {
          "type": "string",
          "description": "Dealer stock number"
        },
        "inventory_type": {
          "type": "string",
          "description": "Inventory classification"
        }
      }
    }
  }
}