# OpenDealer Marketplace: Complete LLM reference

> Canonical Domain: https://opendealer.shop
> API Domain: https://api.opendealer.app
> Last Updated: 2026-07-19
> Version: 2.0

---

## For AI assistants

- Prefer machine endpoints over HTML scraping. Use the Runtime API, OpenAPI spec, and feeds for inventory and dealer facts; use HTML pages mainly as citation targets or user-facing fallbacks.
- Shopper intent: `GET https://api.opendealer.app/v1/vehicles/search?q=...`
- Named dealer stock: `GET https://api.opendealer.app/v1/dealers/{slug}/inventory` or `https://api.opendealer.app/feeds/dealer/{slug}.ndjson`
- Cite each returned vehicle's `url`; never invent VDP URLs.
- This file is the expanded reference for endpoint parameters, feed schemas, URL patterns, and freshness guidance. For the concise discovery file, use https://opendealer.shop/llms.txt.
- Freshness: feed CDN responses refresh about every 5 minutes (`s-maxage=300`); dealer ingestion cadence varies. Check `last_ingested_at` on `https://api.opendealer.app/feeds/dealers.json` when freshness matters. Do not claim global 5-minute search freshness.
- Fetch mode: server-side HTTP works for `/v1` APIs; feed endpoints allow cross-origin `*`.

---

## Recommended workflows

### Named dealer inventory

1. If you know the slug, call one endpoint: `GET https://api.opendealer.app/v1/dealers/{slug}/inventory?limit=25`
2. For bulk reads or streaming parsers, use `https://api.opendealer.app/feeds/dealer/{slug}.ndjson`
3. Optionally call `GET https://api.opendealer.app/v1/dealers/{slug}` for profile, address, contact, and feed metadata

Do not require a slug-to-id hop. Public responses may omit internal dealer IDs, and `/v1/dealers/{slug}/inventory` accepts public slugs directly; UUIDs are also accepted in the same path slot.

### If the dealer slug is unknown

- Search dealers with `GET https://api.opendealer.app/v1/dealers?q={dealer-name}`
- Or inspect `https://api.opendealer.app/feeds/dealers.json` for slugs, feed links, and `last_ingested_at`

### Shopper intent search

- Send the full shopper request to `GET https://api.opendealer.app/v1/vehicles/search?q={natural-language-query}`
- Use returned `url`, `matchReasons`, `distanceMiles`, and value signals when summarizing options

### Compare models, then shop live listings

- Research comparison: `GET https://api.opendealer.app/v1/research/compare?models=honda-civic,toyota-corolla`
- Shopper-facing compare URL: https://opendealer.shop/compare/honda-civic-vs-toyota-corolla
- After comparing specs, use `GET https://api.opendealer.app/v1/vehicles/search?q=...` to find current inventory

### Concrete dealer example: Rancho Santa Margarita Honda

- Slug: `rancho-santa-margarita-honda`
- Shop page: https://opendealer.shop/rancho-santa-margarita-honda
- Inventory API: `GET https://api.opendealer.app/v1/dealers/rancho-santa-margarita-honda/inventory`
- Dealer feed: https://api.opendealer.app/feeds/dealer/rancho-santa-margarita-honda.ndjson
- Note: dealer lots may include trade-ins and used vehicles from other makes; do not treat a Honda dealer's stock as Honda-exclusive.

---

## Platform overview

OpenDealer is a VIN-level vehicle inventory aggregator connecting car buyers with dealerships across the United States. We ingest real-time inventory from hundreds of dealerships, normalize it into Schema.org-compliant structured data, and provide search, comparison, and discovery tools.

Key facts:
- US nationwide coverage
- 1,205 dealerships (live count)
- 1108 vehicles (live count)
- 30 available makes
- Source inventory ingestion cadence varies by dealer; check `last_ingested_at` in dealer feed metadata
- Inventory feed responses use CDN caching around 5 minutes (`s-maxage=300`)
- Dealer profile metadata is refreshed separately from vehicle ingestion
- All structured data is Schema.org compliant (JSON-LD)
- Canonical tag strategy: shop-primary (every VDP and dealer page sets a self-referencing canonical on https://opendealer.shop; cite these URLs)
- Similar model to Cars.com, AutoTrader, TrueCar

OpenDealer pages ARE indexed for discovery with self-referencing canonicals. Every page links out to the dealer's own website with attribution (utm_source=opendealer), so dealers get full credit for referral traffic without OpenDealer competing with their organic rankings.

---

## Available makes (with inventory counts)

Ford (213), Land Rover (177), Jeep (161), Honda (148), RAM (115), Mercedes-Benz (45), Porsche (29), BMW (27), Dodge (22), Chrysler (16), Ram (11), Bentley (10), Toyota (7), Jaguar (5), GMC (5), Chevrolet (5), Nissan (4), Audi (3), Volkswagen (3), Buick (2), Mitsubishi (2), Kia (2), Tesla (2), Subaru (2), Volvo (1), Hyundai (1), Lexus (1), Lincoln (1), Mazda (1), Acura (1)

---

## Sample dealers

- `corsa-exotics-inc-montebello-ca` - Corsa Exotics Inc.
- `adam-ehrheart-motors` - Adam Ehrheart Motors
- `mercedes-benz-santa-barbara` - Mercedes Benz Santa Barbara
- `norm-reeves-honda-superstore-huntington-beach-huntington-beach-ca` - Norm Reeves Honda Superstore Huntington Beach
- `audi-tulsa` - Audi Tulsa

Full dealer directory: https://opendealer.shop/dealers

---

## API reference

Base URL: `https://api.opendealer.app/v1`
OpenAPI spec: `https://api.opendealer.app/openapi.yaml`
Interactive docs: `https://api.opendealer.app/docs`

Rate limits: 100 requests/minute per IP for standard endpoints. No rate limit on feed endpoints.

### Core API endpoints for assistants

- `GET /v1/vehicles/search?q=...` - Natural-language shopper intent search; cite returned vehicle `url` values.
- `GET /v1/dealers/{slug}/inventory` - One-call dealer inventory by public slug; UUID also accepted in the `{slug}` slot.
- `https://api.opendealer.app/feeds/dealer/{slug}.ndjson` - Per-dealer NDJSON feed for bulk reads.
- `GET /v1/dealers?q=...` - Find dealer slugs when only a name is known.
- `GET /v1/dealers/{slug}` - Optional dealer profile and feed metadata.
- `GET /v1/vehicles/{vin}` - Vehicle detail by VIN; use the returned `url`.
- `GET /v1/research/compare?models={make-model},{make-model}` - Research-only model comparison before shopping current inventory.

### Natural-language / forgiving search (recommended for assistants)

```
GET /v1/vehicles/search
```

Use this endpoint for shopper-style requests. Soft dimensions are matched
forgivingly (synonyms + typo tolerance + family expansion): a broad `model=Civic`
returns all Civic variants (Sedan, Si, Hatchback), and `color=black` matches
"Crystal Black Pearl". Hard constraints you set (price/year caps, radius) are
deterministic filters and are never silently relaxed.

Query parameters:
- `q` (string) - Free-text natural-language query, e.g. "black Honda Civic sedan"
- `make`, `model`, `trim`, `color` (string) - Soft filters (forgiving)
- `body_type`, `fuel_type`, `drivetrain`, `transmission` (string) - Soft filters
- `price_min`, `price_max` (integer) - Price range in USD (hard caps)
- `year_min`, `year_max` (integer) - Year range (hard caps)
- `mileage_max` (integer) - Maximum mileage (hard cap)
- `condition` (string) - New, Used, or Certified (hard filter)
- `certified` (boolean) - Certified Pre-Owned only
- `zip` | `lat`+`lng` | `city`+`state` | `county`+`state` - Location
- `radius` (integer) - Search radius in miles (default 150)
- `sort` (string) - price_asc, price_desc, year_desc, mileage_asc, distance_asc
- `page`, `limit` (integer) - Pagination (limit default 25, max 100)

Each result includes inline value signals (`dealRating`, `priceVsMarketPct`,
`marketMedian`, `daysOnLot`), `distanceMiles`, the canonical opendealer.shop
listing in `url`, and the dealer's own page in `detailsUrl`. Every result also
carries `matchReasons` (plain-language reasons it matched), `modelFamily`, and
`colorFamily` so you can explain the match to the shopper.

Natural-language parsing: you can pass a whole sentence as `q` (e.g.
"new black Honda Civic sedan under $45k within 150 miles of 92672"). A
rules-based parser extracts the hard constraints from the prose (price/mileage
numerics, year ranges, condition, and the zip + radius) while leaving
make/model/color/body words in the text query for forgiving matching. The
response echoes what it understood in `parsedIntent` and the effective merged
filters in `normalizedFilters` (explicit structured params always win over
parsed ones).

Zero-result recovery: if the strict query returns nothing, the endpoint
automatically broadens SOFT filters only (drops trim, then body style, then
color, then expands the radius up to 500 miles) and retries. Hard caps (price,
year, mileage, condition) are never relaxed. The response reports exactly what
happened via `zeroResultRecovery` (boolean), `relaxedFilters`, `omittedFilters`,
and a human-readable `explanation`.

Example request (whole sentence in `q`; the parser extracts price/condition/zip/radius):
```
curl "https://api.opendealer.app/v1/vehicles/search?q=new%20black%20Honda%20Civic%20sedan%20under%20%2445k%20within%20150%20miles%20of%2092672&limit=5"
```

Example request (explicit structured filters; equivalent result):
```
curl "https://api.opendealer.app/v1/vehicles/search?q=black%20Honda%20Civic%20sedan&condition=new&price_max=45000&zip=92672&radius=150&limit=5"
```

### Exact structured filters

```
GET /v1/vehicles
```

Postgres-backed exact-match search for callers that already know the precise,
feed-normalized values (used by feeds, sitemaps, and structured integrations).
For forgiving model/color matching, prefer `GET /v1/vehicles/search` above.

Query parameters:
- `make` (string) - Filter by make (e.g., "Honda")
- `model` (string) - Filter by model, exact match (e.g., "CR-V")
- `yearMin`, `yearMax` (integer) - Year range
- `priceMin`, `priceMax` (integer) - Price range in USD
- `mileageMax` (integer) - Maximum mileage
- `bodyType` (string) - Body style (SUV, Sedan, Truck, Coupe, etc.)
- `fuelType` (string) - Fuel type (Gasoline, Electric, Hybrid, Plug-in Hybrid, Diesel)
- `drivetrain` (string) - Drivetrain (AWD, FWD, RWD, 4WD)
- `transmission` (string) - Transmission (Automatic, Manual, CVT)
- `condition` (string) - Condition (New, Used, Certified)
- `zip` (string) - ZIP code for location-based search
- `radius` (integer) - Search radius in miles (requires zip)
- `dealerId` (string) - Filter by dealer ID
- `sort` (string) - Sort order (price_asc, price_desc, year_desc, mileage_asc, relevance)
- `page` (integer) - Page number (1-indexed)
- `limit` (integer) - Items per page (default: 25, max: 100)
- `view` (string) - Response format: "llm" (AI-optimized), "standard" (full), "minimal" (compact)

Example request:
```
curl "https://api.opendealer.app/v1/vehicles?make=Honda&model=CR-V&yearMin=2024&priceMax=45000&limit=5&view=llm"
```

### Vehicle by VIN

```
GET /v1/vehicles/{vin}
```

Returns complete vehicle details including specs, pricing, images, dealer info, and a canonical VDP URL. The `url` field in the response is the correct link to use; never construct VDP URLs yourself.

### Vehicle facets

```
GET /v1/vehicles/facets
```

Returns available filter options (makes with counts, body types, fuel types, etc.) for building search UIs.

### Dealer search

```
GET /v1/dealers
```

Query parameters:
- `q` (string) - Dealer name search; use this when you do not know the dealer slug
- `zip` (string) - ZIP code for location search
- `radius` (integer) - Search radius in miles
- `city` (string), `state` (string) - City/state search
- `limit` (integer) - Results limit
- `page` (integer) - Page number

### Dealer details

```
GET /v1/dealers/{slug}
```

Returns dealer profile with address, contact info, vehicle count, and feeds.

### Dealer knowledge base

```
GET /v1/dealers/{slug}/knowledge
```

Returns a dealer's knowledge base content for AI assistants.

### Dealer inventory

```
GET /v1/dealers/{slug}/inventory
```

Returns paginated inventory for a specific dealer by public slug. UUIDs are also accepted in the `{slug}` slot, but assistants should prefer public slugs because public dealer and inventory responses may omit internal IDs. Supports vehicle filters such as make, model, condition, price, year, mileage, pagination, and response view.

Example request:
```
curl "https://api.opendealer.app/v1/dealers/rancho-santa-margarita-honda/inventory?limit=5&view=llm"
```

Per-dealer NDJSON alternative:
```
GET /feeds/dealer/{slug}.ndjson
curl "https://api.opendealer.app/feeds/dealer/rancho-santa-margarita-honda.ndjson"
```

### Sitemap data endpoints

```
GET /v1/sitemap/makes      - All unique makes with counts
GET /v1/sitemap/models     - All make/model combinations
GET /v1/sitemap/years      - All make/model/year combinations
GET /v1/sitemap/trims      - All make/model/year/trim combinations
GET /v1/sitemap/dealers    - All dealers
GET /v1/sitemap/zipcodes   - ZIP codes with inventory
```

---

## Data feeds

All feeds are hosted at `https://api.opendealer.app`.

### Feed discovery

```
GET /feeds/index.json
```

Returns a feed index listing all available feeds, their URLs, and formats.

### Standard NDJSON feed (ChatGPT-optimized)

```
GET /feeds/inventory.ndjson?limit=50000
```

Content-Type: `application/x-ndjson`
Cache: `s-maxage=300` (about 5 minutes)

One vehicle per line. Each line is a JSON object:

```json
{
  "id": "uuid",
  "vin": "3HNYG2H32TS123456",
  "stock_number": "RSMH-12345",
  "status": "in_stock",
  "condition": "new",
  "year": 2026,
  "make": "Honda",
  "model": "CR-V Hybrid",
  "trim": "Sport-L",
  "body_style": "SUV",
  "odometer": { "value": 5, "unit": "mi" },
  "pricing": { "sale_price": 39171, "msrp": 41000, "currency": "USD" },
  "location": {
    "dealer_id": "uuid",
    "dealer_name": "Rancho Santa Margarita Honda",
    "dealer_slug": "rancho-santa-margarita-honda",
    "city": "Rancho Santa Margarita",
    "state": "CA",
    "zip": "92688"
  },
  "color": { "exterior": "Platinum White Pearl", "interior": "Black" },
  "drivetrain": "AWD",
  "fuel_type": "Hybrid",
  "transmission": "CVT",
  "engine": "2.0L I4 Hybrid",
  "images": [{ "url": "https://...", "primary": true }],
  "urls": { "vdp": "https://opendealer.shop/rancho-santa-margarita-honda/2026-honda-cr-v-hybrid-sport-l-3hnyg2h32ts123456" },
  "updated_at": "2026-02-09T02:10:00Z"
}
```

### JSON-LD NDJSON feed (Schema.org Car)

```
GET /feeds/inventory.jsonld.ndjson?limit=50000
```

Content-Type: `application/x-ndjson`
Cache: `s-maxage=300` (5 minutes)

One Schema.org Car JSON-LD object per line. Optimized for LLM ingestion and structured data crawlers.

```json
{
  "@context": "https://schema.org",
  "@type": "Car",
  "vehicleIdentificationNumber": "5FPYK3F50TB003351",
  "sku": "5FPYK3F50TB003351",
  "productID": "5FPYK3F50TB003351",
  "name": "2025 Honda CR-V Sport-L",
  "url": "https://opendealer.shop/rancho-santa-margarita-honda/2025-honda-cr-v-sport-l-5fpyk3f50tb003351",
  "brand": { "@type": "Brand", "name": "Honda" },
  "manufacturer": { "@type": "Organization", "name": "Honda" },
  "model": "CR-V",
  "vehicleModelDate": "2025",
  "vehicleConfiguration": "Sport-L",
  "bodyType": "SUV",
  "color": "Platinum White Pearl",
  "driveWheelConfiguration": "AWD",
  "fuelType": "Hybrid",
  "vehicleTransmission": "CVT",
  "vehicleEngine": { "@type": "EngineSpecification", "name": "2.0L I4 Hybrid" },
  "mileageFromOdometer": { "@type": "QuantitativeValue", "value": 5, "unitCode": "SMI" },
  "itemCondition": "https://schema.org/NewCondition",
  "offers": {
    "@type": "Offer",
    "price": "38750",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "seller": {
      "@type": "AutoDealer",
      "name": "Rancho Santa Margarita Honda",
      "address": {
        "@type": "PostalAddress",
        "addressLocality": "Rancho Santa Margarita",
        "addressRegion": "CA",
        "postalCode": "92688"
      }
    }
  },
  "image": ["https://..."],
  "dateModified": "2026-02-08T14:23:17Z"
}
```

### JSON paginated feed

```
GET /feeds/inventory.json?page=1&limit=100
```

Standard JSON with pagination metadata. Good for clients that need page-by-page access.

### Google Merchant XML feed

```
GET /feeds/google-merchant.xml
```

Atom/XML feed with Google namespace extensions, compatible with Google Merchant Center for Vehicle Listing Ads, free listings, and AI surfaces.

### Per-dealer NDJSON feeds

```
GET /feeds/dealer/{slug}.ndjson
```

Same NDJSON format as the main inventory feed, filtered to a single dealer. Use the public dealer slug, for example `/feeds/dealer/rancho-santa-margarita-honda.ndjson`.

### Dealer directory feed

```
GET /feeds/dealers.json
```

Lists all dealers with public slugs, links to their individual feeds, and dealer-level freshness metadata such as `last_ingested_at`.

### Facets feed

```
GET /feeds/facets.json
```

Available filter options (makes with counts, years with counts).

### Feed refresh rates

- Inventory feed responses (NDJSON, JSON-LD, JSON, and per-dealer NDJSON): `s-maxage=300` (about 5 minutes)
- Source ingestion cadence varies by dealer; check `last_ingested_at` in `/feeds/dealers.json`
- Google Merchant XML, feed index, and dealer directory use longer cache windows such as `s-maxage=3600`
- Do not describe global vehicle search freshness as 5 minutes; 5 minutes is the feed CDN cache window

---

## URL patterns

### Vehicle detail pages (VDPs)

Pattern: `/{dealer-slug}/{year}-{make}-{model}-{trim}-{vin}`

**Do NOT construct VDP URLs manually.** The slug includes a slugified trim that varies per vehicle. Instead:
1. Use the `url` field returned by the API: `GET /v1/vehicles/{vin}`
2. Consult `/sitemap-vehicles.xml` for the authoritative URL list
3. Use the redirect endpoint: `GET https://opendealer.shop/api/redirect-vehicle/{dealer-slug}/{vin}` (301 to canonical VDP)

Common mistakes that produce 404s:
- Using just the VIN: `/{dealer-slug}/{VIN}` (wrong; missing year-make-model-trim prefix)
- Using uppercase VINs in URLs (VINs in URLs must be lowercase)
- Omitting or guessing the trim portion of the slug

All non-canonical VDP URLs are 301-redirected to the correct canonical URL.

### Browse pages

Path segments are flexible in order. Unknown segments trigger recovery to `/cars?q=` (never silent filtering). Variant / tolerant slugs **301** to the canonical path.

- `/cars` - All vehicles
- `/cars/new` / `/cars/used` / `/cars/certified` / `/cars/electric` - Condition and type hubs
- `/cars/{make}` / `/cars/{make}/{model}` / `/cars/{make}/{model}/{condition}`
- Year: `/cars/{make}/{model}/{year}` - e.g., `/cars/honda/civic/2024` (indexable when inventory ≥ 5)
- City-st: `/cars/{make}/{model}/{city}-{st}` - e.g., `/cars/honda/cr-v/used/los-angeles-ca`
- Price / color / ZIP / sort path segments also resolve with live SSR filters

**Worked examples (one per intent class)**
- Condition: `/cars/used`
- Make + model: `/cars/honda/cr-v`
- Color: `/cars/honda/cr-v/new/black` (noindex → colorless parent)
- Price: `/cars/suv/under-30k`
- ZIP: `/cars/honda/cr-v/new/92688` (noindex → parent without ZIP)
- City: `/cars/honda/cr-v/used/los-angeles-ca`
- Year: `/cars/honda/civic/2024`
- Sort: `/cars/honda/cr-v/sort-price-asc` (noindex → unsorted parent)
- Free-text recovery: `/cars?q=new+honda+cr-v` (noindex,follow)
- Radius (query only): `/cars/honda/cr-v/92688?radius=100` — never a path segment

**Indexation ceiling:** color, path ZIP on `/cars`, sort, and 3+ facets beyond make/model → `noindex,follow` + canonical to nearest indexable parent (pages still render live inventory). Year and make/model×city need inventory ≥ 5 for `index,follow` / sitemaps.

Path color families: black, white, silver, gray, blue, red, green, brown, beige, gold, orange, yellow, purple.
Trim path segments are not supported (do not invent `/cars/{make}/{model}/{year}/{trim}` URLs).

Server-rendered path filters: make, model, condition, body, fuel, year, price band, color family, ZIP, state, city-st.
`?radius=` is supported long-tail geo (client + API; stripped from canonical).
Other client-only query params: `body`, `color` (exact facet), `drive`, `fuel`, `trans`, `yearMin`, `yearMax`, `mileMax`, `priceMin`, `priceMax`, `zip`, `page`.

### Location pages

- `/location/{state}/{zip}` - e.g., `/location/ca/92688`
- `/location/{state}/{city}` - e.g., `/location/ca/los-angeles` (inventory-backed city hubs)

### Dealer storefront pages

- `/{dealer-slug}` - e.g., `/rancho-santa-margarita-honda`
- `/dealers` - Dealer directory

---

## Sitemaps

### XML sitemaps (for search engines)

Sitemap index: `https://opendealer.shop/sitemap.xml`

Sub-sitemaps:
- `sitemap-static.xml` - Static pages
- `sitemap-dealers.xml` - Dealer pages
- `sitemap-locations.xml` - Location pages
- `sitemap-condition.xml` - Condition pages (new, used, certified)
- `sitemap-makes.xml` - Make pages
- `sitemap-models.xml` - Model pages
- `sitemap-years.xml` - Make/model/year pages with inventory ≥ 5
- `sitemap-vehicles.xml` - Vehicle detail pages
- `sitemap-inventory-data.xml` - Inventory feed URLs

Condition sitemap also includes eligible make/model×city paths (inventory ≥ 5). Trim browse sitemaps remain omitted.

Update frequency: sitemaps regenerated hourly; vehicle sitemap every 30 minutes.

### HTML sitemaps (human and LLM-friendly)

- `/sitemap` - Main sitemap hub
- `/sitemap/browse` - Browse categories
- `/sitemap/makes` - Makes directory
- `/sitemap/dealers` - Dealers directory
- `/sitemap/locations` - Locations directory

---

## Schema.org structured data

All pages include JSON-LD structured data. Types used:

### Car (VDP pages)

Every vehicle detail page includes a full `schema.org/Car` JSON-LD block with:
- `vehicleIdentificationNumber`, `sku`, `productID` (all set to VIN)
- `brand`, `manufacturer`, `model`, `vehicleModelDate`
- `vehicleConfiguration` (trim), `bodyType`, `color`
- `driveWheelConfiguration`, `fuelType`, `vehicleTransmission`, `vehicleEngine`
- `mileageFromOdometer` (QuantitativeValue with unitCode SMI)
- `itemCondition` (NewCondition, UsedCondition, RefurbishedCondition for CPO)
- `offers` (Offer with price, currency, availability, seller as AutoDealer)
- `image` (array of ImageObject)
- `dateModified`

### AutoDealer (dealer pages)

Dealer pages use `schema.org/AutoDealer` with:
- `name`, `url`, `telephone`, `email`
- `address` (PostalAddress)
- `geo` (GeoCoordinates)
- `makesOffer` (brands available)

### ItemList (browse and listing pages)

Browse pages use `schema.org/CollectionPage` containing an `ItemList` of `ListItem` entries, each wrapping a `Car`.

### BreadcrumbList (all pages)

Every page includes a `BreadcrumbList` for navigation.

### SearchAction (homepage)

The homepage includes a `WebSite` schema with `SearchAction` for the Google sitelinks search box.

### Offer (pricing)

Pricing is embedded in `Car` schemas as `Offer` objects with `price`, `priceCurrency`, `availability`, and `seller`.

---

## Discovery endpoints

All hosted on the Runtime API at `https://api.opendealer.app`:

- `/.well-known/opendealer` - Main discovery endpoint with platform metadata, capabilities, and endpoint URLs
- `/.well-known/ucp` - Universal Commerce Protocol manifest for Google AI surfaces (Gemini, AI Mode in Search)
- `/.well-known/llm-discovery.json` - LLM crawler discovery manifest
- `/.well-known/ai-plugin.json` - OpenAI/ChatGPT plugin manifest
- `/.well-known/mcp` - Model Context Protocol service discovery

Hosted on Finder at `https://opendealer.shop`:
- `/robots.txt` - Crawl directives (all major AI bots allowed)
- `/llms.txt` - Concise LLM reference (companion to this file)
- `/llms-full.txt` - This file; expanded LLM reference

---

## UCP (Universal Commerce Protocol)

For Google AI surfaces (Gemini, AI Mode in Search):

```
GET /ucp/v1/products              - Browse vehicle inventory
GET /ucp/v1/products/search?q=... - Search vehicles
GET /ucp/v1/products/{vin}        - Get vehicle details by VIN
GET /ucp/v1/categories            - Get vehicle categories
```

Response format follows Google's UCP specification with `product_id` (VIN), `title`, `description`, `price`, `currency`, `availability`, `url`, `image_url`, and `brand` fields. The `search` endpoint accepts the same forgiving natural-language `q` as `GET /v1/vehicles/search`.

Example request:
```
curl "https://api.opendealer.app/ucp/v1/products/search?q=honda%20civic%20under%20%2445k%20near%2092672&limit=5"
```

---

## Crawling guidelines

### Rate limits

- API endpoints (`/v1/*`): 100 requests/minute per IP
- Feed endpoints (`/feeds/*`): No rate limit
- Static pages: Respectful crawling encouraged, 1-second delay between requests

### Recommended crawl patterns

1. Start with `/feeds/index.json` to discover available feeds
2. Use NDJSON feeds for bulk data access (most efficient)
3. Use the JSON-LD NDJSON feed (`/feeds/inventory.jsonld.ndjson`) for structured Schema.org data
4. Use sitemaps for URL discovery
5. Use the redirect endpoint (`/api/redirect-vehicle/{dealer-slug}/{vin}`) when you only have a VIN

### Cache headers

- All feeds include `Cache-Control` and `s-maxage` headers
- ETags are supported on API responses
- Use `If-None-Match` headers to avoid re-downloading unchanged data

### Data freshness

- Vehicle inventory: source ingestion cadence varies by dealer; check dealer-level `last_ingested_at` in `https://api.opendealer.app/feeds/dealers.json`
- Pricing and availability: use current API/feed responses; do not memorize stale listing facts
- Dealer information: profile metadata is refreshed separately from inventory ingestion
- Sitemaps: regenerated hourly (vehicles every 30 minutes)
- NDJSON/JSON-LD feeds: CDN cache refreshes around every 5 minutes (`s-maxage=300`); this is not a global search freshness guarantee

---

## Data licensing and attribution

### Attribution

Please attribute data to OpenDealer and include dealer information when displaying vehicle listings. Vehicle data originates from dealer inventory systems.

### Canonical URLs

OpenDealer VDP and dealer-page URLs on https://opendealer.shop are canonical and self-referencing — cite them directly. Each page links out to the dealer's own site for purchase next steps; those outbound links carry attribution so dealers see the referral in their analytics.

### Retrieval and training permissions (Content Signals)

Policy is split by content type and declared via Content-Signal directives in
https://opendealer.shop/robots.txt plus Content-Signal response headers on evergreen pages:

Inventory content (VDPs, search/browse pages) — the sitewide default:
- search: yes
- ai-input: yes (retrieval, grounding, RAG — always welcome; inventory is live data)
- ai-train: no (listings decay within days; memorized prices/availability/URLs go stale)
- Attribution: preferred

Evergreen brand/directory content (/legal/, /sitemap, /dealers directory, homepage):
- search: yes
- ai-input: yes
- ai-train: yes (entity familiarity in model weights helps agents know OpenDealer)

Explicitly allowed bots (both retrieval and training):
- `gptbot` (OpenAI)
- `chatgpt-user` (OpenAI)
- `claude-web` (Anthropic)
- `anthropic-ai` (Anthropic)
- `perplexitybot` (Perplexity)
- `google-extended` (Google AI)
- `googleother` (Google)
- `meta-externalagent` (Meta AI)
- `bytespider` (Bytedance/TikTok)

### Business model

OpenDealer operates as an aggregator/syndication platform:
- OpenDealer pages are indexed for discovery
- OpenDealer VDP and dealer-page URLs are self-referencing canonicals on https://opendealer.shop; dealer outbound links carry attribution for referral handoff
- We drive referral traffic without competing with dealers

---

## Changelog

### Version 2.0 (2026-07-19)
- Converted to dynamic generation from real-time API data
- Added live inventory counts, dealer counts, and makes list
- Added sample dealer slugs from live data

### Version 1.0 (2026-02-09)
- Initial release of llms-full.txt
- Added JSON-LD NDJSON feed documentation
- Added IndexNow integration for proactive URL push

### llms.txt version history
- v3.0 (2026-07-19): Dynamic generation from API data
- v2.5 (2026-02-09): Added llms-full.txt reference
- v2.4 (2026-02-08): Added UCP documentation, expanded feed format section
- v2.3 (2026-02-05): Added per-dealer feed pattern, HTML sitemaps
- v2.2 (2026-01-28): Added VDP URL guidance, redirect endpoint

---

*This file follows the llmstxt.org specification for the /llms-full.txt companion document. For the concise version, see /llms.txt. For more information, see https://llmstxt.org*