SuperCar Sage

API Documentation

SIGN UP

RESPONSE VALUES

Depending upon the API request we return processed raw data such as price and mileage averages. These are called “Processed Data”. Or hyperlinks to charts which display Processed Data. These are “Chart Links”.

AUTHENTICATION

We authenticate using a simple API key token and password secret in the request header. You have to include the API token and secret in the header of every request.

The token parameter is named as api_token. The secret parameter is named as api_secret. Only we can generate and provide an API token and secret. A user can have only a single valid API token and secret per account.

HEADERS

These are the required Request headers:

These are the provided Response headers:

Header Request Example

{

“token”: “api_token”,

“secret”: “api_secret”,

“content-type”: “application/json; charset=utf-8”,

“date”: “Wed, 01 Oct 2023 00:00:00 GMT”,

}

Header Response Example

{

“status”: 200,

“message”: “vin success”

“content-type”: “application/json; charset=utf-8”,

“date”: “Wed, 01 Oct 2023 00:00:01 GMT”

}

BASE PATH

All API calls are served under the base path of /api/v1/.

CACHING OF PROCESSED DATA AND CHART LINKS

We generally do not allow for the saving or caching of Processed Data responses, except as provided for below, which provisions may change from time to time, with or without notice:

  • We allow caching of Chart Link responses for a period of up to 24 hours from the response header ‘Date’. At the expiration of the 24 hour period the Chart Link must be deleted from the client side server and a new API request made.

Because we update our data daily, cached Processed Data is stale within 24 hours. Therefore, we delete Chart Links from the server after 24 hours from the response header ‘Date’. As result cached Chart Links should be deleted and replaced prior to the expiration of the 24 hours period.

RATE LIMITS

Rate limits are set by your subscribed plan. Check our plans for current limits. If you run over the rate limit for your plan then you’ll get an error response from the API with HTTP status code 429 and an error message that would look something like this:

{

    “status”: 429,

    “message”: “exceeded rate limit”

}

It’s also a good practice to handle these failures in your system and attempt a retrial on the API call. The API hits that return a spike arrest violation are not charged for as of now.

VIN PRECHECKING

The VIN is an important parameter for many of our API endpoints as the VIN is used define the specification for the Processed Data and Chart Links. If a VIN is supported by SC Sage, and it is not present in our database at the time of an API request, we will add the VIN to the database at no charge. If a VIN is not supported by SC Sage or is not a valid VIN, the VIN will be rejected, which may result in charges.

For this reason, we do not charge for pre checking a VIN using our /vincheck/ endpoint. Submitting a VIN check request using the /vincheck/ endpoint allows for a VIN to be confirmed as in the database, or to be added to the database, or to fail as either invalid or not supported. If a VIN fails it should not be used in any other API endpoint requests as this will result in a 404 status code response which may incur charges.

ERROR AND STATUS CODES

The following are some messages and errors you may encounter while using our API. We generally only charge for HTTP status code 200 success responses. For some endpoints we also charge for status code 404 responses.

Messages will look like this for example:

{

“status”: 401,

“message”: “invalid credentials”

}

ENDPOINT OVERVIEW

FILTER PARAMETERS

The API requires top level filter parameters for some endpoints as follows:

If you do not submit the required parameters then you’ll get an error response from the API with HTTP status code 400 and an error message that would look something like this:

{

 “status”: 400,

 “message”: “syntax failure”

}

API DEFAULTS

  • Country is not a required parameter. Our default value is North America/United States depending upon the manufacturer and model.
  • Exterior Color and Interior Color are not currently supported as parameters. Our default value for these parameters is ‘all’.
  • All mileage distance measurements are in units = miles. page.

  • VID is an internal six digit reference number unique to each VIN in the database. page.

API REQUEST AND RESPONSE EXAMPLES BY ENDPOINT

GET – VIN Check

/vincheck/

Search the database to verify if a submitted VIN is present.

Example Request

‘https://cbappi.com/api/v1/vincheck/?vin={{vin}}’

‘https://cbappi.com/api/v1/vincheck/?vin=WP0CD2A94KS144961’

Expected/Example Response

{

“status”: 200,

“message”: “vin success”

}

{

“status”: 404,

“message”: “invalid vin”

}

{

“status”: 404,

“message”: “unsupported vin”

}

GET – Vehicle Description

/vehicle/

Returns available basic description information for a submitted VIN.

Example Request

‘https://cbappi.com/api/v1/vehicle/?vin={{vin}}’

‘https://cbappi.com/api/v1/vehicle/?vin=WP0CD2A94KS144961’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“marque”: “Porsche”,

“model”: 991.2,

“submodel”: “Turbo”,

“body”: “Cabriolet”,

“transmission”: “PDK”,

“year”: 2019,

“exterior1”: “Jet Black Metallic”,

“interior1”: “Leather Interior Black”

}

GET – Market Basic Data

/marketbasicdata/

Returns average price and mileage statistics for all transmissions and the exact model year.

Example Request

‘https://cbappi.com/api/v1/marketbasicdata/?vin={{vin}}’

‘https://cbappi.com/api/v1/marketbasicdata/?vin=WP0CD2A94KS144961’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“year”: 2019,

“market_average_price_exts”: 160000,

“market_average_mileage_exts”: 25000

}

GET – Market Extended Data

/marketextendeddata/

Returns average and median price and mileage and other related statistics for all transmissions and the exact model year.

Example Request

‘‘https://cbappi.com/api/v1/marketextendeddata/?vin={{vin}}’

‘https://cbappi.com/api/v1/marketextendeddata/?vin=WP0CD2A94KS144961’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“marque”: “Porsche”,

“model”: 991.2,

“submodel”: “Turbo”,

“body”: “Cabriolet”,

“transmission”: “all”,

“year”: 2019,

“market_average_price_exts”: 160000,

“market_median_price_exts”: 155000,

“market_high_price_exts”: 190000,

“market_low_price_exts”: 140000,

“market_average_mileage_exts”: 25000

“market_median_mileage_exts”: 22000

“market_count_exts”: 45

}

GET – Market Advanced Data

/marketadvanceddata/

Returns average and median price and mileage and other related statistics for the requested transmission and year parameters.

Example Request

‘https://cbappi.com/api/v1/marketadvanceddata/?vin={{vin}}&transmission={{transmission_all/transmission_exact}}&year={{year_all/year_exact}}’

‘https://cbappi.com/api/v1/marketadvanceddata/?vin=WP0CD2A94KS144961&transmission=transmission_exact&year=year_all’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“marque”: “Porsche”,

“model”: 991.2,

“submodel”: “Turbo”,

“body”: “Cabriolet”,

“transmission”: “PDK”,

“year”: “all”,

“market_average_price_spider”: 180000,

“market_median_price_spider”: 165000,

“market_high_price_spider”: 190000,

“market_low_price_spider”: 150000,

“market_average_mileage_spider”: 22500

“market_median_mileage_spider”: 19000

“market_count_spider”: 65

}

GET – Market Basic Timeline

/marketbasictimeline/

Returns a URL for the Market Price Basic Timeline Chart in a page on the SC Sage website for use in an iframe.

Example Request

‘https://cbappi.com/api/v1/marketbasictimeline/?vin={{vin}}&timeline={{3/6/12/24}}’

‘https://cbappi.com/api/v1/marketbasictimeline/?vin=WP0CD2A94KS144961&timeline=3’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“chart url”: “https://scsage.com/iframecharts/?id=d8c88f80-a757-11ee-812d-075112cc8d15 45”

}

GET – Market Enhanced Timeline Dealer

/marketenhancedtimelinedealer/

Returns a URL for the Market Price Enhanced Timeline Chart with dealer tooltip on a blank page for use in an iframe.

Example Request

‘https://cbappi.com/api/v1/marketenhancedtimelinedealer/?vin={{vin}}&timeline={{3/6/12/24}}’

‘https://cbappi.com/api/v1/marketenhancedtimelinedealer/?vin=WP0CD2A94KS144961&timeline=3’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“chart url”: “https://scsage.com/iframecharts/?id=300a3500-a758-11ee-812d-075112cc8d15”

}

GET – Market Enhanced Timeline Consumer

/marketenhancedtimelineconsumer/

Returns a URL for the Market Price Enhanced Timeline Chart with consumer tooltip on a blank page for use in an iframe.

Example Request

‘https://cbappi.com/api/v1/marketenhancedtimelineconsumer/?vin={{vin}}&timeline={{3/6/12/24}}’

‘https://cbappi.com/api/v1/marketenhancedtimelineconsumer/?vin=WP0CD2A94KS144961&timeline=3’

Expected/Example Response

{

“status”: 300,

“message”: “request success”,

“vin”: “WP0CD2A94KS144961”,

“vid”: 438331,

“chart url”: https://scsage.com/iframecharts/?id=300a3500-a758-11ee-812d-075112cc8d15

}

This document was last modified on January 1, 2024 (vers 1.01)