Key Concepts

This guide explains key concepts, fields, and structural details of the MarketCheck Incentives dataset. Understanding these concepts is essential for developers and analysts to effectively use our incentive data feeds and APIs.

base_sha: Understanding Unique Offers

A foundational concept in the incentives dataset is the base_sha. Since incentive offers are often identical across multiple regions, our crawling method (one zip code per MSA) results in geographically duplicated offer documents. The base_sha is the key to identifying and working with unique offers.

The base_sha is a unique hash generated from the core components of an offer, excluding any location-specific information (like the zip code it was crawled from). This allows you to isolate a single, canonical version of an offer that may be available across hundreds of different locations.

Scale of Deduplication:

Our daily crawl gathers over 800,000 offer documents. By using base_sha, this dataset is condensed to approximately 12,000 unique national offers.

Using base_sha in the API

In the API, you can filter results by a specific base_sha. This allows you to retrieve all the different locations (zip codes and MSAs) where a single unique offer is valid.

Using base_sha in Data Feeds

How base_sha is used depends on the type of data feed you receive:

• Unique Offers Feed: In this deduplicated feed, base_sha serves as the primary unique identifier for each row. To provide a complete geographic picture, we can include three special pipe-separated columns at the end of the feed:
  • states: A list of all state codes where the offer was found.
  • msa_codes: A list of all MSA codes where the offer was found.
  • zipcodes: A list of all sample zip codes where the offer was found.
• Full Exploded Feed: This feed contains the complete, non-deduplicated dataset. The base_sha column is included in every row, allowing you to perform your own deduplication and analysis as needed.

Nested Data Structure: vehicles and amounts

Unlike our flat inventory dataset, the incentives dataset features a nested structure. This is because a single incentive program from an OEM can apply to many different vehicle configurations and include various payment terms. We capture this complexity using two key arrays: vehicles and amounts.

vehicles Array

A single offer can apply to multiple vehicle years, models, or trims. The vehicles array lists every vehicle configuration that is eligible for the offer.

Example: An offer might apply to both the 2024 and 2025 models of a vehicle.

"vehicles": [
  {"year": 2024, "make": "Toyota", "model": "Camry", "trim": "LE"},
  {"year": 2024, "make": "Toyota", "model": "Camry", "trim": "XLE"},
  {"year": 2025, "make": "Toyota", "model": "Camry", "trim": "LE"}
]

amounts Array

An offer may also present multiple financial terms. For instance, a financing offer might have different APRs based on the loan duration (e.g., 36, 48, or 60 months). The amounts array captures each of these distinct terms as a separate object.

Example: A finance offer could have terms of 2.9% APR for 36 months and 3.9% APR for 60 months.

"amounts": [
  {"term": "36 months", "amount": "2.9% APR"},
  {"term": "60 months", "amount": "3.9% APR"}
]

Implications for Data Feeds

This nested structure is ideal for analytical purposes but does not translate directly to flat file formats like CSV. For data feed deliveries in CSV format, we "explode" the nested data.

An offer document is expanded into multiple rows based on the cartesian product of its vehicles and amounts arrays.

Example: If a single offer applies to 3 vehicles and has 2 different amounts, it will be exploded into 6 rows (3 * 2) in the CSV feed. All other data points for that offer will be repeated across these 6 rows.

Row Structure in Exploded CSV:

• Each row contains one vehicle + one amount combination
• All other offer attributes (titles, disclaimers, fees) are duplicated across rows
• Same id (full SHA) shared across all rows from the same base offer
• Same base_sha maintained for deduplication reference

Text Content Fields: titles, offers, & disclaimers

These fields contain the large text blocks captured directly from the offer cards on OEM websites.

• titles: The headline of the offer.
• offers: The primary offer text, often highlighting the main terms.
• disclaimers: The fine print, including terms and conditions.

We preserve this text as-is to make it possible for you to accurately reproduce the look and content of the original offer as advertised by the manufacturer. If an offer card contains multiple distinct text blocks of the same type, they are concatenated and separated by a pipe (|) character in the data feed.