> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driv.ly/llms.txt
> Use this file to discover all available pages before exploring further.

# Listings Search

> Learn how to search for vehicles using the Listings Search API.

export const CustomCallout = ({children, variant, icon}) => <>
    {variant === 'tip' && <div className="my-4 px-5 py-4 overflow-hidden rounded-xl border border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10">
        <div className="flex items-start space-x-3">
          {icon && <div className="mt-0.5 w-4">
              <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="CustomTip">
                <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
              </svg>
            </div>}
          <div className="flex-1 text-sm prose text-wrap text-emerald-900 dark:text-emerald-200">
            {children}
          </div>
        </div>
      </div>}
    {variant === 'note' && <div className="my-4 px-5 py-4 overflow-hidden rounded-xl border border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10">
        <div className="flex items-start space-x-3">
          {icon && <div className="mt-0.5 w-4">
              <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="CustomNote">
                <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
              </svg>
            </div>}
          <div className="flex-1 text-sm prose text-wrap text-sky-900 dark:text-sky-200">
            {children}
          </div>
        </div>
      </div>}
    {variant === 'info' && <div className="my-4 px-5 py-4 overflow-hidden rounded-xl border border-zinc-500/20 bg-zinc-50/50 dark:border-zinc-500/30 dark:bg-zinc-500/10">
        <div className="flex items-start space-x-3">
          {icon && <div className="mt-0.5 w-4">
              <svg viewBox="0 0 20 20" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="flex-none w-5 h-5 text-zinc-400 dark:text-zinc-300" aria-label="CustomInfo">
                <path d="M8 0C3.58125 0 0 3.58125 0 8C0 12.4187 3.58125 16 8 16C12.4187 16 16 12.4187 16 8C16 3.58125 12.4187 0 8 0ZM8 14.5C4.41563 14.5 1.5 11.5841 1.5 8C1.5 4.41594 4.41563 1.5 8 1.5C11.5844 1.5 14.5 4.41594 14.5 8C14.5 11.5841 11.5844 14.5 8 14.5ZM9.25 10.5H8.75V7.75C8.75 7.3375 8.41563 7 8 7H7C6.5875 7 6.25 7.3375 6.25 7.75C6.25 8.1625 6.5875 8.5 7 8.5H7.25V10.5H6.75C6.3375 10.5 6 10.8375 6 11.25C6 11.6625 6.3375 12 6.75 12H9.25C9.66406 12 10 11.6641 10 11.25C10 10.8359 9.66563 10.5 9.25 10.5ZM8 6C8.55219 6 9 5.55219 9 5C9 4.44781 8.55219 4 8 4C7.44781 4 7 4.44687 7 5C7 5.55313 7.44687 6 8 6Z"></path>
              </svg>
            </div>}
          <div className="flex-1 text-sm prose text-wrap text-zinc-900 dark:text-zinc-200">
            {children}
          </div>
        </div>
      </div>}
    {variant === 'warning' && <div className="my-4 px-5 py-4 overflow-hidden rounded-xl border border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10">
        <div className="flex items-start space-x-3">
          {icon && <div className="mt-0.5 w-4">
              <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="CustomWarning">
                <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
              </svg>
            </div>}
          <div className="flex-1 text-sm prose text-wrap text-amber-900 dark:text-amber-200">
            {children}
          </div>
        </div>
      </div>}
    {variant === 'check' && <div className="my-4 px-5 py-4 overflow-hidden rounded-xl border border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10">
        <div className="flex items-start space-x-3">
          {icon && <div className="mt-0.5 w-4">
              <svg className="text-green-600 dark:text-green-400/80 w-3.5 h-auto" fill="currentColor" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512" aria-label="CustomCheck">
                <path d="M438.6 105.4C451.1 117.9 451.1 138.1 438.6 150.6L182.6 406.6C170.1 419.1 149.9 419.1 137.4 406.6L9.372 278.6C-3.124 266.1-3.124 245.9 9.372 233.4C21.87 220.9 42.13 220.9 54.63 233.4L159.1 338.7L393.4 105.4C405.9 92.88 426.1 92.88 438.6 105.4H438.6z"></path>
              </svg>
            </div>}
          <div className="flex-1 text-sm prose text-wrap text-emerald-900 dark:text-emerald-200">
            {children}
          </div>
        </div>
      </div>}
  </>;

## 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](#get-listings)       | Retrieve detailed information about vehicles from the Listings API. |
| [Pagination](#pagination)           | Navigate through large result sets using pagination.                |
| [Search Listings](#search-listings) | Filter listings by make, model, year, price, and more.              |
| [Sort Listings](#sort-listings)     | Sort search results by price, mileage, and year.                    |
| [Facets](#facets)                   | Categorize search results based on specific attributes.             |
| [Photos](#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.

<Accordion title="Get Listings" defaultOpen="true">
  ```json theme={null}
  {
    "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": {...}
  }
  ```
</Accordion>

***

## 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.

<p class="font-medium">
  <code class="p-2 flex flex-wrap items-center justify-start">
    <div class="px-1 h-8 flex items-center mr-2 rounded-[0.3rem] text-[0.55rem] leading-tight font-bold bg-green-400/20 text-green-700 dark:bg-green-400/20 dark:text-green-400 text-base">
      GET
    </div>

    <span> [https://listings.vin/?vehicle.make=ford\&vehicle.model=mustang](https://listings.vin/?vehicle.make=ford\&vehicle.model=mustang)</span>
  </code>
</p>

<Card title="Search Listings Parameters" icon="magnifying-glass-chart" href="/data/reference/listings/search">
  Learn more about search parameters
</Card>

***

## 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:

<p class="font-medium">
  <code class="p-2 flex flex-wrap items-center justify-start">
    <div class="px-1 h-8 flex items-center mr-2 rounded-[0.3rem] text-[0.55rem] leading-tight font-bold bg-green-400/20 text-green-700 dark:bg-green-400/20 dark:text-green-400 text-base">
      GET
    </div>

    <span>
      {" "}

      [https://listings.vin/?vehicle.make=ford\&vehicle.model=mustang\&sort=price.asc](https://listings.vin/?vehicle.make=ford\&vehicle.model=mustang\&sort=price.asc)
    </span>
  </code>
</p>

<Card title="Sort Listings" icon="sort" href="/data/reference/listings/sorting/price">
  Learn more about sorting options
</Card>

***

## Facets

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.

### How Facets Work

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.

<Accordion title="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)                                  |
</Accordion>

### Using Facets

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:

<Accordion title="Example Facets" defaultOpen="true">
  ```json theme={null}
  {
    "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",
        ...
      }
    }
  }
  ```
</Accordion>

***

## 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.

<CustomCallout variant="note" icon>
  Learn more about our [Photos API](/data/vehicle#vehicle-photos).
</CustomCallout>

***

## Next Steps

Review the API reference for the Listings Search API

<Card title="Reference – Listings Search" icon="link" href="/data/reference/listings">
  Explore the Listings Search API endpoint and parameters.
</Card>