> ## Documentation Index > Fetch the complete documentation index at: https://api.visor.vin/docs/llms.txt > Use this file to discover all available pages before exploring further. # How the Data Works > Understand what Visor listing, VIN, dealer, facet, and usage data means in day-to-day API work. Visor is an inventory API. The main thing you query is a **listing**: a vehicle, identified by VIN when available, attached to the dealer Visor attributes as the public seller for that market record. The API is built for practical search, comparison, and monitoring. It is not an unfiltered data dump. Visor reconciles multiple observations, normalizes vehicle facts, filters out common duplicate and temporary-disappearance noise, and serves a stable public contract through `/v1`. ## The short version * `/v1/listings` returns active inventory by default. * `/v1/facets` shows which values actually exist for your current filters. * `/v1/vins/{vin}` returns the current or latest known record for one VIN. * `/v1/dealers` returns public dealer profiles and attributed active listing counts. * Listing and dealer counts are deduplicated and attributed; they can differ from raw dealer website counts. * Null values mean "not confidently available," not zero. ## Listings, VINs, and dealers A **listing** is the API's market record for a vehicle at a dealer. It has a stable `id`, a `vin`, vehicle fields such as `year`, `make`, `model`, and `trim`, commercial fields such as `price`, `miles`, and `vdp_url`, and dealer fields such as `dealer_id`, `dealer_name`, `city`, and `state`. A **VIN** is the vehicle identity. VIN detail is useful when you care about the vehicle across listing state changes. A VIN can be active now, sold, missing from active inventory, or unknown to Visor. Unknown VINs return `404 not_found_error`. A **dealer** is the public seller profile attached to inventory. Dealer search returns profile data and `listing_count`, which is the current active inventory Visor attributes to that dealer after VIN-level deduplication. ## Inventory modes | Mode | How to request it | What it means | | -------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Active inventory | Omit `inventory_status`, or use `inventory_status=active` | Current public inventory that Visor believes is still available. | | Sold inventory | Use `inventory_status=sold` or `sold_within_days=30` | Historical listings that have been missing from the dealer's inventory feed for at least three days and passed sold-quality checks. | | Historical active snapshot | Use `snapshot_date=YYYY-MM-DD` | Active inventory as of a prior date. Cannot be combined with sold inventory filters. | Use active inventory for shopper-facing search and current market scans. Use sold inventory for recent market history. Use `snapshot_date` when you need to answer "what was active on this date?" ## Deduplication and attribution The public API is deduplicated around VIN-level inventory. If the same VIN appears in multiple places, Visor serves the best public listing row and attributes it to the dealer it believes owns the listing. This is why: * `/v1/listings` is usually better than collecting and merging public dealer pages yourself. * `dealer.listing_count` can be lower than a dealer's raw website count. * `/v1/dealers/{dealer_id}/listings` can omit a VIN observed elsewhere when Visor attributes that VIN to another dealer. * Listing totals can shift as inventory is refreshed or better evidence arrives. For integrations, store both `id` and `vin`. Use `id` when revisiting a specific listing record, and use `vin` when tracking the vehicle across listing changes. ## Freshness and change Vehicle inventory changes constantly. Counts, prices, photos, dealer attribution, and even build details can change between requests. Collection responses include `pagination.total`, but that total is a count at request time. Treat it as a paging aid, not a durable snapshot. If you need repeatable historical analysis, use `snapshot_date` for active inventory or sold inventory filters for market exits. ## Prices, MSRP, and discounts `price` is the main advertised price in whole dollars that the dealer displays for the listing when Visor has a usable value. Depending on how the dealer presents pricing, it may or may not include fees, add-ons, incentives, taxes, registration, or other adjustments. It can be `null` when a price is missing, zero-like, or not reliable enough to serve. VIN and listing detail responses can also include nullable `pricing` detail when supported provider data is available. `pricing` does not replace `price`; it exposes named pricing calculations and customer-safe provider row evidence for the listing. VIN detail returns it at `data.latest_listing.pricing`; listing detail returns it at `data.pricing`. | Pricing field | Meaning | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `displayed_provider_current_price_usd` | Provider-displayed listing price for broad shopper consumption at observation time. It excludes MSRP fallback and does not imply the lowest eligible price. | | `seller_total_before_taxes_and_registration_usd` | Comparable broad-buyer seller-side total before government taxes, title, registration, license, lien, and similar statutory charges. | | `seller_total_before_manufacturer_incentives_usd` | Dealer-controlled seller total before manufacturer-funded incentives and rebates, including broadly available temporary programs. | | `dealer_adjusted_vehicle_price_usd` | Vehicle price after dealer-controlled vehicle adjustments, before seller fees, seller add-ons, government charges, and manufacturer incentives. | | `line_items` | Provider-observed pricing row evidence. Each item includes amount, raw label, normalized role, applicability, direction, row key/order, and subtype when available. | `msrp` on listing collections is combined MSRP when available. `discount_from_msrp` is based on that combined MSRP, not base MSRP. VIN and listing detail responses expose both: | Field | Meaning | | -------------------- | -------------------------------------------------------------------------- | | `base_msrp` | Base vehicle MSRP when available. | | `combined_msrp` | Base MSRP plus installed options when available. | | `discount_from_msrp` | `(price - combined_msrp) / combined_msrp`; negative values are below MSRP. | Use `discount_from_msrp=-0.12` as "12 percent below MSRP." The `sort=discount` order returns the strongest below-MSRP discounts first. ## Days on market `days_on_market` is Visor's best public estimate of how long the listing has been observed on market. It uses the best available inventory date when one is trustworthy and otherwise falls back to the first observed date. Use it for relative sorting, freshness checks, and market scanning. Do not treat it as a dealer-certified lot-age guarantee. ## Sold inventory Sold inventory is inferred from listing disappearance plus quality checks that suppress common inventory-feed noise. A listing is considered sold only after it has been missing from the dealer's inventory feed for at least three days and passes those checks. If a listing has been missing for less than three days, Visor treats it as missing, not sold. Missing records are not returned in sold listing searches yet; VIN detail can show `status: "missing"` when the VIN is known but no longer appears in active inventory. This means sold data is intentionally conservative: * Very recent exits can take at least three days to appear as sold. * Temporary feed gaps should be less likely to show up as sales. * A sold record can still have null fields when the last known listing evidence lacked that value. Use `sold_within_days` for normal recent-market workflows, and request `sold_date` in `fields` when listing the sold collection. ## Build, options, and features Build data is normalized from vehicle and listing evidence. For many VINs, Visor can return year, make, model, trim, version, body type, drivetrain, fuel type, transmission, engine, color, seating, doors, cylinders, and assembly location. Use `include=options` on VIN or listing detail when you need decoded installed options: * `options_packages` is the public listing field containing manufacturer option/package codes. * `options` is the enriched array of `{ code, name, msrp }` objects returned when `include=options` is requested. * `features` is a normalized feature list useful for filtering and broad discovery. Build and option fields can be null when Visor cannot confidently resolve them. ## Facets and discoverability Use facets before building a narrow search. Vehicle naming varies: `F-150`, `f150`, and other user-entered forms may not be the exact public value in inventory. Facets return: | Response path | Contents | | -------------------------- | ---------------------------------------------------------------------------- | | `data.total` | Matching listing count for the filters. | | `data.facets.` | Categorical buckets such as make, model, trim, color, features, and options. | | `data.range_facets.` | Numeric buckets for price, MSRP, miles, and days on market. | | `data.stats.` | Numeric min, max, count, missing, mean, median, and standard deviation. | Facet metrics are useful for comparisons, but small buckets suppress metric values with `null_reason: "insufficient_sample"`. Always look at `count` before trusting a bucket-level metric. ## Geography Listing latitude and longitude refer to dealer location when available. `distance_miles` is computed only when you provide `postal_code` or `latitude` and `longitude`. Use: * `state` for broad market filters. * `postal_code` plus `radius` for local search. * `latitude` and `longitude` when your app already has coordinates. * `bbox` for map viewport searches. ## Nulls and missing values Null means Visor is not serving a confident value for that field. It does not mean "zero," "false," or "not applicable" unless the field says so. Common examples: * `price: null` means no usable listed price. * `miles: null` means no usable odometer value. * `msrp: null` means combined MSRP was not confidently resolved. * `photo_urls: []` means no public listing photos were available. * `dealer.phone: null` means no public phone number is available in the dealer profile. Build resilient clients that can display partial records. ## What not to infer Do not treat the public API as: * An unfiltered data dump. * Proof that a vehicle is legally sold. * A valuation or appraisal product. * A guarantee that every dealer, listing, option, photo, or price on the internet is present. * A guarantee that a dealer website count and Visor's attributed count will match. The API is strongest when you use it as a normalized inventory and market-data surface: discover values with facets, fetch listings with explicit filters, revisit VINs or listing IDs for detail, and treat nulls and changing totals as normal inventory behavior. ## Recommended workflow 1. Start with `/v1/facets` to discover valid makes, models, trims, colors, features, and option codes. 2. Query `/v1/listings` with `limit`, `offset`, and explicit `fields`. 3. Use `include=price_history` or `include=options` only when you need those enriched details. 4. Store both `id` and `vin`. 5. Use `/v1/vins/{vin}` for vehicle tracking and `/v1/dealers/{dealer_id}` for seller context. 6. Monitor cost and request classes with `/v1/usage`. See [Filters and Facets](/docs/filters-and-facets) for request syntax and [Glossary](/docs/glossary) for field-by-field terminology.