How the Data Works

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

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. More detailed pricing information is coming soon. 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: 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: 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 for request syntax and Glossary for field-by-field terminology.