Listings Search

Overview

The Listings Search API sources vehicle listings from dealerships, auctions, and private sellers, offering detailed information from millions of listings. Including year, make, model, price, mileage, and more.

Capabilities	Description
Get Listings	Retrieve detailed information about vehicles from the Listings API.
Pagination	Navigate through large result sets using pagination.
Search Listings	Filter listings by make, model, year, price, and more.
Sort Listings	Sort search results by price, mileage, and year.
Facets	Categorize search results based on specific attributes.
Photos	Access high-quality images for specific vehicles.

Get Listings

The base URL for the Listings API is listings.vin. You can access the API by making HTTP requests to this URL.

Get Listings

{
  "api": {
    "icon": "🚗",
    "name": "listings.vin",
    "description": "Driv.ly VIN database"
  },
  "total": 2122738,
  "links": {
    "self": "http://listings.vin/?undefined",
    "next": "https://listings.vin/?page=2",
    "last": "https://listings.vin/?page=21228"
  },
  "data": [
    {
      "vin": "1GYKPFRS4RZ701252",
      "url": "http://listings.vin/1GYKPFRS4RZ701252",
      "vehicle": {
        "vin": "1GYKPFRS4RZ701252",
        "squishVin": "1GYKPFRSRZ",
        "year": 2024,
        "make": "Cadillac",
        "model": "XT6",
        "trim": "Premium Luxury",
        "series": "Premium Luxury 4dr SUV AWD (3.6L 6cyl 9A)",
        "bodyStyle": "SUV",
        "type": ["Crossover", "Luxury", "Performance/Sports", "SUV"],
        "style": "4dr SUV",
        "drivetrain": "4WD",
        "engine": "3.6L 6Cyl gasoline",
        "cylinders": 6,
        "fuel": "Regular Unleaded",
        "transmission": "Automatic",
        "confidence": 0.995,
        "interiorColor": "Black",
        "exteriorColor": "White",
        "baseMsrp": 56995,
        "baseInvoice": 54145,
        "doors": 4,
        "seats": 7
      },
      "retailListing": {
        "vdp": "/cadillac-xt6#vin=1GYKPFRS4RZ701252",
        "price": 58911,
        "miles": 7494,
        "used": true,
        "cpo": false,
        "carfaxUrl": "https://www.carfax.com/VehicleHistory/p/Report.cfx?vin=1GYKPFRS4RZ701252&partner=FRD_2",
        "dealer": "Ken Batchelor Cadillac",
        "city": "San Antonio",
        "state": "TX",
        "primaryImage": "https://retail.photos.vin/1GYKPFRS4RZ701252-1.jpg",
        "photoCount": 30,
        "margin": null
      },
      "score": 3
    },
    {
      "vin": "JM3KFBBL3R0465418",
      "url": "http://listings.vin/JM3KFBBL3R0465418",
      "vehicle": {
        "vin": "JM3KFBBL3R0465418",
        "squishVin": "JM3KFBBLR0",
        "year": 2024,
        "make": "Mazda",
        "model": "CX-5",
        "trim": "2.5 S Select",
        "series": "2.5 S Select 4dr SUV AWD (2.5L 4cyl 6A)",
        "bodyStyle": "SUV",
        "type": ["Crossover", "SUV"],
        "style": "4dr SUV",
        "drivetrain": "AWD",
        "engine": "2.5L 4Cyl gasoline",
        "cylinders": 4,
        "fuel": "Regular Unleaded",
        "transmission": "Automatic",
        "confidence": 0.995,
        "interiorColor": "Black",
        "baseMsrp": 29300,
        "doors": 4,
        "seats": 5
      },
      "retailListing": {
        "vdp": "/mazda-cx+5#vin=JM3KFBBL3R0465418",
        "price": 29550,
        "miles": 4,
        "used": false,
        "cpo": false,
        "carfaxUrl": "https://www.carfax.com/VehicleHistory/p/Report.cfx?vin=JM3KFBBL3R0465418&partner=FRD_2",
        "dealer": "Capital Lincoln Mazda of Cary",
        "city": "Cary",
        "state": "NC",
        "primaryImage": "https://retail.photos.vin/JM3KFBBL3R0465418-1.jpg",
        "photoCount": 4,
        "margin": null
      },
      "score": 3
    },
    ...
  ],
  "facets": {...}
}

Pagination

Pagination is supported for large result sets. Use the page parameter to navigate through the results. For example, page=2 will return the second page of results. Limit the number of results per page using the limit parameter. For example, limit=10 will return 10 results per page.

Search Listings

Simply make a GET request to listings.vin with your desired search parameters. You can filter by make, model, year, price, mileage, and more.

GET

https://listings.vin/?vehicle.make=ford&vehicle.model=mustang

Search Listings Parameters

Learn more about search parameters

Sort Listings

You can sort the search results by mileage, price, and year to find the best deals quickly. Simply add the sort parameter to your request. For example, to sort by price in ascending order:

GET

https://listings.vin/?vehicle.make=ford&vehicle.model=mustang&sort=price.asc

Sort Listings

Learn more about sorting options

Facets are powerful filters that categorize search results based on specific attributes, enabling users to quickly identify and access relevant data points within a large dataset. When a user performs a search, the API not only retrieves relevant listings but also provides a summary of attributes related to those listings in the form of facets. Each facet category will display the count of listings corresponding to each attribute, allowing users to gauge the prevalence of specific characteristics within the search results.

Available Facets

Facet Category	Description	Example Facets
`Years`	Filter listings by year of manufacture	2024 (873515)
`Makes`	Group listings by vehicle make	Chevrolet (240343)
`Models`	Categorize listings by vehicle model	Silverado 1500 (72285)
`Trims`	Break down by specific trims	Limited (98611)
`Series`	Differentiate listings by vehicle series	Limited 4dr SUV 4WD (3.6L 6cyl 8A) (15920)
`Types`	Differentiate listings by vehicle type	SUV (1001980)
`Engine`	Facet by engine type	2.0L 4Cyl gasoline (337112)
`Cylinders`	Filter by the number of cylinders	4 (1107200)
`Transmissions`	Distinguish listings by transmission type	Automatic (1889687)
`Drivetrain`	Filter by drivetrain	AWD (674110)
`Int Color`	Organize listings by Interior Color options	Black (1311956)
`Ext Color`	Sort listings by Exterior Colors options	White (556523)
`Doors`	Filter by the number of doors	2-Door (237901)
`Fuel`	Classify listings by type of fuel used	Regular Unleaded (1295264)
`States`	View listings based on the state where the vehicle is located	FL (10348)
`Prices`	Facet by price ranges	$20000-$24000 (219594)
`Mileage`	Categorize by mileage	0-7000 (1280236)
`Accidents`	Indicate the number of accidents reported	0 (49999)

The facets for listings are encapsulated within a dedicated object at the root of each listings.vin request, and are named after the corresponding field. Each facet is represented as an object, with the field values serving as keys and the count of matching results as values. For example, the following JSON response includes facets for makes, models, and years:

Example Facets

{
  "data": [...],
  "facets": {
    "models": {
      "Silverado 1500 (72285)": "http://listings.vin/?vehicle.model=Silverado+1500",
      "F-150 (69924)": "http://listings.vin/?vehicle.model=F-150",
      "1500 (44608)": "http://listings.vin/?vehicle.model=1500",
      ...
    },
    "types": {
      "SUV (1001980)": "http://listings.vin/?vehicle.type=SUV",
      "Crossover (890502)": "http://listings.vin/?vehicle.type=Crossover",
      "Performance/Sports (414979)": "http://listings.vin/?vehicle.type=Performance%2FSports",
      ...
    },
    "exteriorColor": {
      "White (556523)": "http://listings.vin/?vehicle.exteriorColor=White",
      "Gray (426637)": "http://listings.vin/?vehicle.exteriorColor=Gray",
      "Black (411803)": "http://listings.vin/?vehicle.exteriorColor=Black",
      ...
    },
    "fuel": {
      "Regular Unleaded (1295264)": "http://listings.vin/?vehicle.fuel=Regular+Unleaded",
      "Premium Unleaded (Recommended) (255301)": "http://listings.vin/?vehicle.fuel=Premium+Unleaded+%28Recommended%29",
      "Gasoline (172455)": "http://listings.vin/?vehicle.fuel=Gasoline",
      ...
    },
    "makes": {
      "Chevrolet (240343)": "http://listings.vin/?vehicle.make=Chevrolet",
      "Ford (237155)": "http://listings.vin/?vehicle.make=Ford",
      "Jeep (168141)": "http://listings.vin/?vehicle.make=Jeep",
      ...
    },
    "trims": {
      "Limited (98611)": "http://listings.vin/?vehicle.trim=Limited",
      "LT (68295)": "http://listings.vin/?vehicle.trim=LT",
      "XLT (67690)": "http://listings.vin/?vehicle.trim=XLT",
      ...
    },
    "drivetrain": {
      "AWD (674110)": "http://listings.vin/?vehicle.drivetrain=AWD",
      "4WD (579549)": "http://listings.vin/?vehicle.drivetrain=4WD",
      "FWD (574559)": "http://listings.vin/?vehicle.drivetrain=FWD",
      ...
    },
    "accidents": {
      "0 (49999)": "http://listings.vin/?autocheck.numberOfAccidents=0",
      "1 (13170)": "http://listings.vin/?autocheck.numberOfAccidents=1",
      "2 (2889)": "http://listings.vin/?autocheck.numberOfAccidents=2",
      ...
    },
    "cylinders": {
      "0 (4418)": "http://listings.vin/?vehicle.cylinders=0",
      "1 (1)": "http://listings.vin/?vehicle.cylinders=1",
      "2 (315)": "http://listings.vin/?vehicle.cylinders=2",
      ...
    },
    "years": {
      "2025 (12049)": "http://listings.vin/?vehicle.year=2025",
      "2024 (873515)": "http://listings.vin/?vehicle.year=2024",
      "2023 (252467)": "http://listings.vin/?vehicle.year=2023",
      ...
    },
    "states": {
      "FL (10348)": "http://listings.vin/?wholesaleListing.state=FL",
      "TX (8312)": "http://listings.vin/?wholesaleListing.state=TX",
      "GA (4389)": "http://listings.vin/?wholesaleListing.state=GA",
      ...
    },
    "transmissions": {
      "Automatic (1889687)": "http://listings.vin/?vehicle.transmission=Automatic",
      "Manual (109726)": "http://listings.vin/?vehicle.transmission=Manual",
      "Direct Drive (63488)": "http://listings.vin/?vehicle.transmission=Direct+Drive",
      ...
    },
    "interiorColor": {
      "Black (1311956)": "http://listings.vin/?vehicle.interiorColor=Black",
      "Gray (376117)": "http://listings.vin/?vehicle.interiorColor=Gray",
      "Brown (132500)": "http://listings.vin/?vehicle.interiorColor=Brown",
      ...
    },
    "engine": {
      "2.0L 4Cyl gasoline (337112)": "http://listings.vin/?vehicle.engine=2.0L+4Cyl+gasoline",
      "2.5L 4Cyl gasoline (212733)": "http://listings.vin/?vehicle.engine=2.5L+4Cyl+gasoline",
      "3.6L 6Cyl gasoline (190968)": "http://listings.vin/?vehicle.engine=3.6L+6Cyl+gasoline",
      ...
    },
    "series": {
      "Limited 4dr SUV 4WD (3.6L 6cyl 8A) (15920)": "http://listings.vin/?vehicle.series=Limited+4dr+SUV+4WD+%283.6L+6cyl+8A%29",
      "SV 4dr Sedan (2.0L 4cyl CVT) (11777)": "http://listings.vin/?vehicle.series=SV+4dr+Sedan+%282.0L+4cyl+CVT%29",
      "XLT 4dr SuperCrew 4WD 6.5 ft. SB (5.0L 8cyl 10A) (10599)": "http://listings.vin/?vehicle.series=XLT+4dr+SuperCrew+4WD+6.5+ft.+SB+%285.0L+8cyl+10A%29",
      ...
    },
    "prices": {
      "5000-9000 (90097)": "http://listings.vin/?retailListing.price=5000-9000",
      "9000-13000 (126325)": "http://listings.vin/?retailListing.price=9000-13000",
      "13000-17000 (159588)": "http://listings.vin/?retailListing.price=13000-17000",
      ...
    },
    "mileage": {
      "0-7000 (1280236)": "http://listings.vin/?retailListing.miles=0-7000",
      "7000-13000 (74138)": "http://listings.vin/?retailListing.miles=7000-13000",
      "13000-19000 (78895)": "http://listings.vin/?retailListing.miles=13000-19000",
      ...
    }
  }
}

Photos

We provide access to retail and wholesale photos for every listing in our photos.vin CDN.

Retail and Wholesale Photos

Retail photos are publicly available online and typically sourced from dealerships. These photos are generally of higher quality and verified for accuracy.
Wholesale photos are sourced from auctions and accessing these photos requires provider credentials. These photos may not always be accurate or up to date.

Learn more about our Photos API.

Next Steps

Review the API reference for the Listings Search API

Reference – Listings Search

Explore the Listings Search API endpoint and parameters.

Data

Guides

API Reference

Overview

Get Listings

Search Listings

Search Listings Parameters

Sort Listings

Sort Listings

Facets

How Facets Work

Using Facets

Photos

Retail and Wholesale Photos

Next Steps

Reference – Listings Search

Data

Guides

API Reference

​Overview

​Get Listings

​Pagination

​Search Listings

Search Listings Parameters

​Sort Listings

Sort Listings

​Facets

​How Facets Work

​Using Facets

​Photos

​Retail and Wholesale Photos

​Next Steps

Reference – Listings Search

Overview

Get Listings

Pagination

Search Listings

Sort Listings

Facets

How Facets Work

Using Facets

Photos

Retail and Wholesale Photos

Next Steps