Gets oem incentive listings for the given search criteria

GET

/search/car/incentive/oem

OEM Incentive Search

This endpoint is the meat of the API and serves many purposes. This API produces a list of currently active oem incentive from the market for the given search criteria. The API results are limited to allow pagination upto 10000 rows.
The search API facilitates the following use cases -

Search Cars around a given geo-point within a given radius

Search cars for a specific year / make / model or combination of these

Search cars matching multiple year, make, model combinatins in the same search request

Filter results by most car specification attributes

Search for similar cars by VIN or Taxonomy VIN

Filter cars within a given price / miles / days on market (dom) range

Specify a sort order for the results on price / miles / dom / listed date

Search cars for a given City / State combination

Get Facets to build the search drill downs

10.

Get Market averages for price/miles/dom for your search

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://marketcheck-prod.apigee.net/v2/search/car/incentive/oem'

Response Example

200 - Example 1

{
    "facets": {
        "base_exterior_color": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "base_interior_color": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "body_subtype": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "body_type": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "car_type": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "carfax_1_owner": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "carfax_clean_title": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "city": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "cylinders": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "data_source": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "dealer_id": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "dealer_type": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "doors": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "drivetrain": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "engine": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "engine_aspiration": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "engine_block": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "engine_size": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "exterior_color": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "fuel_type": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "interior_color": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "make": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "model": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "seller_name": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "seller_name_o": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "seller_type": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "source": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "state": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "transmission": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "trim": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "trim_o": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "trim_r": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "vehicle_type": [
            {
                "count": 0,
                "item": "string"
            }
        ],
        "year": [
            {
                "count": 0,
                "item": "string"
            }
        ]
    },
    "listings": [
        {
            "base_ext_color": "string",
            "base_int_color": "string",
            "build": {
                "antibrake_sys": "string",
                "body_subtype": "string",
                "body_type": "string",
                "city_miles": "string",
                "city_mpg": 0,
                "cylinders": 0,
                "doors": 0,
                "drivetrain": "string",
                "engine": "string",
                "engine_aspiration": "string",
                "engine_block": "string",
                "engine_measure": "string",
                "engine_size": 0,
                "fuel_type": "string",
                "highway_miles": "string",
                "highway_mpg": 0,
                "made_in": "string",
                "make": "string",
                "model": "string",
                "opt_seating": "string",
                "overall_height": "string",
                "overall_length": "string",
                "overall_width": "string",
                "powertrain_type": "string",
                "short_trim": "string",
                "std_seating": "string",
                "steering_type": "string",
                "tank_size": "string",
                "transmission": "string",
                "trim": "string",
                "trim_r": "string",
                "vehicle_type": "string",
                "year": 0
            },
            "carfax_1_owner": true,
            "carfax_clean_title": true,
            "data_source": "string",
            "dealer": {
                "city": "string",
                "country": "string",
                "county": "string",
                "dealer_type": "string",
                "dealership_group_name": "string",
                "id": 0,
                "latitude": "string",
                "longitude": "string",
                "msa_code": "string",
                "name": "string",
                "phone": "string",
                "seller_email": "string",
                "state": "string",
                "street": "string",
                "website": "string",
                "zip": "string"
            },
            "dist": 0,
            "dom": 0,
            "dom_180": 0,
            "dom_active": 0,
            "exterior_color": "string",
            "financing_options": [
                {
                    "down_payment": 0,
                    "down_payment_percentage": 0,
                    "estimated_monthly_payment": 0,
                    "loan_apr": 0,
                    "loan_term": 0
                }
            ],
            "first_seen_at": 0,
            "first_seen_at_date": "string",
            "heading": "string",
            "id": "string",
            "in_transit": true,
            "interior_color": "string",
            "inventory_type": "string",
            "is_certified": 0,
            "is_translated": true,
            "last_seen_at": 0,
            "last_seen_at_date": "string",
            "leasing_options": [
                {
                    "down_payment": 0,
                    "estimated_monthly_payment": 0,
                    "lease_term": 0
                }
            ],
            "media": {
                "photo_links": [
                    "string"
                ],
                "photo_links_cached": [
                    "string"
                ]
            },
            "miles": 0,
            "model_code": "string",
            "msrp": 0,
            "price": 0,
            "price_change_percent": 0,
            "ref_miles": "string",
            "ref_miles_dt": 0,
            "ref_price": "string",
            "ref_price_dt": 0,
            "scraped_at": 0,
            "scraped_at_date": "string",
            "seller_type": "string",
            "source": "string",
            "stock_no": "string",
            "title_type": "string",
            "vdp_url": "string",
            "vin": "string"
        }
    ],
    "num_found": 0,
    "range_facets": {
        "dom": {},
        "dom_180": {},
        "dom_active": {},
        "finance_down_payment": {},
        "finance_emp": {},
        "finance_loan_apr": {},
        "finance_loan_term": {},
        "lease_down_payment": {},
        "lease_emp": {},
        "lease_term": {},
        "miles": {},
        "msrp": {},
        "price": {}
    },
    "stats": {
        "dom": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "dom_180": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "dom_active": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "finance_down_payment": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "finance_down_payment_per": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "finance_emp": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "finance_loan_apr": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "finance_loan_term": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "lease_down_payment": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "lease_emp": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "lease_term": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "miles": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "msrp": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        },
        "price": {
            "count": 0,
            "max": 0,
            "mean": 0,
            "median": 0,
            "min": 0,
            "missing": 0,
            "stddev": 0,
            "sum": 0,
            "sum_of_squares": 0
        }
    }
}

Request

Query Params

api_key

string

optional

The API Authentication Key. Mandatory with all API calls.

offer_type

string

optional

The type of the incentive

year

string

optional

To filter listing on their year

make

string

optional

To filter listings on their make

model

string

optional

To filter listings on their model

trim

string

optional

To filter listing on their trim

msrp

string

optional

MSRP range to filter listings with the msrp in the range given. Range to be given in the format - min-max e.g. 1000-5000

apr

string

optional

APR range to filter listings with the msrp in the range given. Range to be given in the format - min-max e.g. 1000-5000

monthly

string

optional

To filter listing on Monthly payment amount, usually populated in Lease offers

monthly_per_thousand

string

optional

To filter listing on monthly amount to be paid by customer for every $1000 financed at the advertised APR rate

down_payment

string

optional

To filter listing on down payment offer on car

due_at_signing

string

optional

To filter listing on total amount due at signing, that usually includes first month payment, down payment, acquisition fee etc

security_deposit

string

optional

To filter listing on security deposit required for the offer

disposition_fee

string

optional

To filter listing on disposition fee of the car

acquisition_fee

string

optional

To filter listing on acquisition fee of the car

duration

string

optional

To filter listing on offer duration in months

dealer_contribution

string

optional

To filter listing on any contribution from dealer's side

mileage_charge

string

optional

Mileage Charge Range range to filter listings with the msrp in the range given. Range to be given in the format - min-max e.g. 100-1000

mileage_charge_limit

string

optional

To filter listing on mileage charge limit the offer is valid up to under the default clauses

cashback_amount

string

optional

To filter listing on cashback amounts listed in offer

cashback_target_group

string

optional

To filter listing on the demographic or any other entity for whom this cashback offer is for. Not all target groups are identified but the most common ones are tagged like Military, Grad students Current owners etc

lease_end_purchase_option

string

optional

To filter listing on amount at the lease end to pay for buying the car

net_capitalised_cost

string

optional

To filter listing on net capitalised cost of the car

gross_capitalised_cost

string

optional

To filter listing on gross capitalised cost of the car

total_monthly_payment

string

optional

To filter listing on gross capitalised cost of the car

zip

string

optional

To filter listing on ZIP around which they are listed

city

string

optional

To filter listing on City in which they are listed

state

string

optional

To filter listing on State in which they are listed

country

string

optional

To filter listing on Country in which they are listed

latitude

number

optional

Latitude component of location

longitude

number

optional

Longitude component of location

radius

integer

optional

Radius around the search location (Unit - Miles)

search_text

string

optional

To search a substring across entire document

last_seen_range

string

optional

Last seen date range to filter listings with the last seen in the range given. Range to be given in the format [YYYYMMDD] - min-max e.g. 20190523-20190623

first_seen_range

string

optional

First seen date range to filter listings with the first seen in the range given. Range to be given in the format [YYYYMMDD] - min-max e.g. 20190523-20190623

sort_by

string

optional

Sort by field. Default sort field is distance from the given point

sort_order

string

optional

Sort order - asc or desc. Default sort order is asc

rows

integer

optional

Number of results to return. Default is 10. Max is 50

start

integer

optional

Page number to fetch the results for the given criteria. Default is 0. Pagination is allowed only till first 10000 results for the search and sort criteria. The page value can be only between 1 to 10000/rows

facets

string

optional

The comma separated list of fields for which facets are requested. Facets could be requested in addition to the listings for the search. Please note - The API calls with lots of facet fields may take longer to respond.

range_facets

string

optional

The comma separated list of numeric fields for which range facets are requested. Range facets could be requested in addition to the listings for the search. Please note - The API calls with lots of range facet fields may take longer to respond.

facet_sort

string

optional

Control sort order of facets with this parameter with default sort being on count, Other available sort is alphabetical sort, which can be obtained by using index as value for this param

stats

string

optional

The list of fields for which stats need to be generated based on the matching listings for the search criteria. The stats consists of mean, max, average and count of listings based on which the stats are calculated for the field. Stats could be requested in addition to the listings for the search. Please note - The API calls with the stats fields may take longer to respond.

Responses

🟢200List of all oem incentive listings matching the search & filter criteria

application/json

Body

Search query response

facets

object (CarSearchFacets)

optional

base_exterior_color

array[object (FacetItem) {2}]

optional

base_interior_color

array[object (FacetItem) {2}]

optional

body_subtype

array[object (FacetItem) {2}]

optional

body_type

array[object (FacetItem) {2}]

optional

car_type

array[object (FacetItem) {2}]

optional

carfax_1_owner

array[object (FacetItem) {2}]

optional

carfax_clean_title

array[object (FacetItem) {2}]

optional

city

array[object (FacetItem) {2}]

optional

cylinders

array[object (FacetItem) {2}]

optional

data_source

array[object (FacetItem) {2}]

optional

dealer_id

array[object (FacetItem) {2}]

optional

dealer_type

array[object (FacetItem) {2}]

optional

doors

array[object (FacetItem) {2}]

optional

drivetrain

array[object (FacetItem) {2}]

optional

engine

array[object (FacetItem) {2}]

optional

engine_aspiration

array[object (FacetItem) {2}]

optional

engine_block

array[object (FacetItem) {2}]

optional

engine_size

array[object (FacetItem) {2}]

optional

exterior_color

array[object (FacetItem) {2}]

optional

fuel_type

array[object (FacetItem) {2}]

optional

interior_color

array[object (FacetItem) {2}]

optional

make

array[object (FacetItem) {2}]

optional

model

array[object (FacetItem) {2}]

optional

seller_name

array[object (FacetItem) {2}]

optional

seller_name_o

array[object (FacetItem) {2}]

optional

seller_type

array[object (FacetItem) {2}]

optional

source

array[object (FacetItem) {2}]

optional

state

array[object (FacetItem) {2}]

optional

transmission

array[object (FacetItem) {2}]

optional

trim

array[object (FacetItem) {2}]

optional

trim_o

array[object (FacetItem) {2}]

optional

trim_r

array[object (FacetItem) {2}]

optional

vehicle_type

array[object (FacetItem) {2}]

optional

year

array[object (FacetItem) {2}]

optional

listings

array[object (BaseListing) {43}]

optional

base_ext_color

string

optional

Base exterior color of the car

base_int_color

string

optional

Base interior color of the car

build

object (Build)

optional

Describes the Car specification

carfax_1_owner

boolean

optional

Flag to indicate whether listing is carfax_1_owner

carfax_clean_title

boolean

optional

Flag to indicate whether listing is carfax_clean_title

data_source

string

optional

Data source of the listing

dealer

object (NestDealer)

optional

dist

number <double>

optional

Distance of the car's location from the specified user lcoation

dom

integer

optional

Days on Market value for the car based on current and historical listings found in the Marketcheck database for this car

dom_180

integer

optional

Days on Market value for the car based on current and last 6 month listings found in the Marketcheck database for this car

dom_active

integer

optional

Days on Market value for the car based on current and last 30 days listings found in the Marketcheck database for this car

exterior_color

string

optional

Exterior color of the car

financing_options

array[object (ListingFinance) {5}]

optional

Array of all finance offers for this listing

first_seen_at

integer

optional

Listing first seen at first scraped timestamp

first_seen_at_date

string

optional

Listing first seen at first scraped date

heading

string

optional

Listing title as displayed on the source website

string

optional

Unique identifier representing a specific listing from the Marketcheck database

in_transit

boolean

optional

in_transit of the listing

interior_color

string

optional

Interior color of the car

inventory_type

string

optional

Inventory type of car

is_certified

integer

optional

Certified car

is_translated

boolean

optional

is_translated of the listing

last_seen_at

integer

optional

Listing last seen at (most recent) timestamp

last_seen_at_date

string

optional

Listing last seen at (most recent) date

leasing_options

array[object (ListingLease) {3}]

optional

Array of all finance offers for this listing

media

object (ListingNestMedia)

optional

miles

integer

optional

Odometer reading / reported miles usage for the car

model_code

string

optional

model_code of the listing

msrp

integer

optional

MSRP for the car

price

integer

optional

Asking price for the car

price_change_percent

number <double>

optional

Percentage difference between the cars's current price and ref_price i.e. last reported price

ref_miles

string

optional

Last Odometer reading / reported miles usage for the car. If the asking miles value is not or is available then the last_miles could perhaps be used. last_miles is the miles for the car listed on the source website as of last_miles_dt date

ref_miles_dt

integer

optional

The date at which the last miles was reported online. This is earlier to last_seen_date

ref_price

string

optional

Last reported price for the car. If the asking price value is not or is available then the last_price could perhaps be used. last_price is the price for the car listed on the source website as of last_price_dt date

ref_price_dt

integer

optional

The date at which the last price was reported online. This is earlier to last_seen_date

scraped_at

number

optional

Listing last seen at date timestamp

scraped_at_date

string

optional

Listing last seen at date

seller_type

string

optional

Seller type for the car

source

string

optional

Source domain of the listing

stock_no

string

optional

Stock number of car in dealers inventory

title_type

string

optional

title_type of the listing

vdp_url

string

optional

Vehicle Details Page url of the specific car

vin

string

optional

VIN for the car

num_found

integer

optional

The number of listings found

range_facets

object (CarSearchRangeFacets)

optional

dom

object

optional

dom_180

object

optional

dom_active

object

optional

finance_down_payment

object

optional

finance_emp

object

optional

finance_loan_apr

object

optional

finance_loan_term

object

optional

lease_down_payment

object

optional

lease_emp

object

optional

lease_term

object

optional

miles

object

optional

msrp

object

optional

price

object

optional

stats

object (CarSearchStats)

optional

dom

object (StatsItem)

optional

dom_180

object (StatsItem)

optional

dom_active

object (StatsItem)

optional

finance_down_payment

object (StatsItem)

optional

finance_down_payment_per

object (StatsItem)

optional

finance_emp

object (StatsItem)

optional

finance_loan_apr

object (StatsItem)

optional

finance_loan_term

object (StatsItem)

optional

lease_down_payment

object (StatsItem)

optional

lease_emp

object (StatsItem)

optional

lease_term

object (StatsItem)

optional

miles

object (StatsItem)

optional

msrp

object (StatsItem)

optional

price

object (StatsItem)

optional

🔴500Error

Modified at 2023-08-15 07:36:55

Compute relative rank for car listings.

get client filters