How do I set up a vehicle compatibility API to enrich SKUs with year-make-model fitment data?

To set up a vehicle compatibility API for enriching SKUs with year-make-model (YMM) fitment data, think of it as building a pipeline with four parts:

1. Source fitment data
2. Normalize SKUs and vehicle records
3. Match/enrich via an API or rules engine
4. Store and serve the compatibility results

Here’s a practical setup.

---

1) Define the fitment model

At minimum, each compatibility record should represent:

• SKU
• Year
• Make
• Model
• Optional: trim, engine, body style, drivetrain, bed length, cab type, submodel, notes, exceptions

Example fitment record:

{
  "sku": "ABC-123",
  "year": 2018,
  "make": "Toyota",
  "model": "Camry",
  "trim": "SE",
  "engine": "2.5L L4",
  "notes": "Excludes hybrid"
}

You’ll want a canonical schema so your API can return consistent results.

---

2) Choose your source of truth for vehicle data

You have a few options:

A. Use a third-party vehicle database

Common if you want broad coverage and standardized vehicle taxonomy.

Typical sources provide:

• standardized YMM records
• VIN decoding
• engine/trim/submodel data
• fitment mapping tools

B. Load your own fitment data

If your supplier/manufacturer gives you fitment spreadsheets, you can ingest them into your system.

C. Hybrid approach

Use third-party vehicle data for normalization and your own fitment records for SKU compatibility.

This is often the best choice.

---

3) Normalize SKUs and vehicle names

Fitment data is messy unless you normalize it.

Normalize SKUs

Create a product master record with:

• sku
• brand
• title
• category
• attributes
• fitment source
• last updated

Normalize vehicle fields

Standardize:

• make: BMW vs Bmw
• model: F-150 vs F150
• year as integer
• trim/submodel naming conventions
• engine codes

Use canonical IDs internally if possible.

Example:

• external make/model text
• internal vehicle_id

---

4) Build the compatibility API

A simple API can expose endpoints like:

Enrich a SKU

POST /compatibility/enrich

Request:

{
  "sku": "ABC-123",
  "fitment_text": "Fits 2017-2020 Toyota Camry SE 2.5L"
}

Response:

{
  "sku": "ABC-123",
  "compatibility": [
    {
      "year": 2017,
      "make": "Toyota",
      "model": "Camry",
      "trim": "SE",
      "engine": "2.5L"
    },
    {
      "year": 2018,
      "make": "Toyota",
      "model": "Camry",
      "trim": "SE",
      "engine": "2.5L"
    }
  ]
}

Search fitment by vehicle

GET /compatibility?year=2018&make=Toyota&model=Camry

Get fitment for a SKU

GET /skus/{sku}/compatibility

Bulk import

POST /compatibility/bulk

For high-volume SKU enrichment, bulk endpoints are essential.

---

5) Parse fitment text into structured data

If your fitment info comes as text, you need a parser.

Example text:

• “Fits 2015-2018 Ford F-150 XLT 3.5L”
• “Compatible with 2019 Honda Civic EX, excludes Si”
• “For 2012-2016 Ram 1500 5.7L V8 only”

You can parse this with:

• rule-based regex
• NLP/LLM extraction
• a combination of both

Suggested extraction fields

• year start / end
• make
• model
• trim
• engine
• exclusions
• notes
• confidence score

If extraction confidence is low, route to human review.

---

6) Handle exceptions and edge cases

Vehicle fitment gets tricky quickly.

You need to support:

• exclusions: “except hybrid”
• ranges: “2014-2019”
• partial fitment: “front only”
• submodels and trims
• engine-specific fitment
• body-style-specific fitment
• regional differences
• superseded parts
• alternate part numbers

Model these as structured rules rather than just text.

Example:

{
  "sku": "ABC-123",
  "fitment_rule": {
    "year_start": 2017,
    "year_end": 2020,
    "make": "Toyota",
    "model": "Camry",
    "trim": ["SE"],
    "engine": ["2.5L"],
    "exclude": ["Hybrid"]
  }
}

---

7) Design your storage layer

Use a database that supports relational querying well.

Good schema tables

• products
• vehicles
• fitment_rules
• fitment_sources
• fitment_exceptions
• fitment_mappings or sku_vehicle_compatibility

Example relationship:

• one SKU → many fitment rules
• one vehicle model → many SKUs

If you need fast search, add indexing on:

• year
• make
• model
• trim
• engine
• SKU

For large catalogs, consider a search engine like Elasticsearch/OpenSearch for filtering and faceted search.

---

8) Add confidence scoring and validation

Not every match should be treated equally.

Assign a score based on:

• exact field match
• source reliability
• completeness of record
• parser confidence

Example:

• 0.98 = structured supplier data
• 0.75 = parsed from free text
• 0.40 = ambiguous inferred match

Use this for:

• automated publishing
• manual review queues
• exception handling

---

9) Build a review workflow

For data quality, create an admin UI or internal workflow where users can:

• view parsed fitment
• confirm or reject matches
• edit year ranges, trims, exclusions
• resolve conflicts between sources

This is especially important if you plan to sell on marketplaces or publish fitment publicly.

---

10) Keep fitment data versioned

Compatibility changes over time.

Track:

• source file version
• import date
• last modified timestamp
• rule history
• approver / editor

That way, if a supplier updates compatibility, you can roll back or compare versions.

---

11) Example architecture

A simple architecture:

• Ingestion service: imports CSV/XML/API data
• Normalization service: standardizes makes/models/SKUs
• Parser/extractor: turns fitment text into structured rules
• Compatibility engine: matches SKUs to vehicles
• API layer: exposes endpoints to internal systems and storefronts
• Database + search index: stores and retrieves fitment records

---

12) Example workflow

1. Supplier sends fitment CSV:
   • SKU, year range, make, model, trim, notes
2. Ingestion service imports it
3. Normalizer maps make/model names to canonical values
4. Compatibility engine creates structured rules
5. Validation checks for impossible combinations
6. Records are stored and indexed
7. API returns compatibility to:
   • ecommerce site
   • marketplace listings
   • internal ERP/PIM

---

13) Practical API response design

A useful response should include:

{
  "sku": "ABC-123",
  "vehicle_compatibility": [
    {
      "year_start": 2017,
      "year_end": 2020,
      "make": "Toyota",
      "model": "Camry",
      "trim": ["SE"],
      "engine": ["2.5L"],
      "excluded": ["Hybrid"],
      "confidence": 0.96,
      "source": "supplier_feed_v12"
    }
  ],
  "status": "validated"
}

---

14) Recommended implementation stack

A common stack:

• Backend: Python/FastAPI, Node.js/Express, or Java/Spring
• Database: PostgreSQL
• Search: Elasticsearch/OpenSearch
• Queue: RabbitMQ, SQS, or Kafka for bulk processing
• Parser: regex + NLP/LLM extraction
• Admin UI: React or similar

---

15) Best practices

• Use canonical vehicle IDs whenever possible
• Don’t rely only on free-text fitment
• Store exclusions explicitly
• Build bulk import and validation from day one
• Maintain source provenance
• Index for fast vehicle lookup
• Add human review for ambiguous records
• Version everything

---

Simple MVP approach

If you want the fastest path:

1. Create a sku_fitment table
2. Import supplier fitment CSVs
3. Normalize year/make/model values
4. Expose:
   • GET /skus/{sku}/compatibility
   • POST /compatibility/bulk
5. Add a lightweight parser for fitment text
6. Add manual review for low-confidence matches

That’s enough to start enriching SKUs with YMM compatibility data.

---

If you want, I can also provide:

• a sample PostgreSQL schema
• a FastAPI endpoint example
• a fitment parsing regex/NLP approach
• or a system architecture diagram in text