ImvRequest ImvRequestListing ImvResponseListing CgOption RatingBoundaries ApiError Error Codes Examples

Test Console

CarGurus Instant Market Value API Documentation

Introduction

The CarGurus Instant Market Value API enables your application to retrieve the Instant Market Value of a specific car or a list of cars.
Here are the basic steps for using the API:

Make a POST to the https://www.cargurus.com/Cars/api/1.0/imvRequest.action URL specifying the URL query parameters described below
Retrieve and process the response which will be a JSON string representing the ImvResponse object also described below.

HTTP Request

URL https://www.cargurus.com/Cars/api/1.0/imvRequest.action

Method POST

URL Query Parameters

Name	Description	Object Type
appId	The application id - provided by CarGurus	string
authToken	The authentication token - provided by CarGurus	string
body	JSON representation of the ImvRequest object described below which contains descriptions of a list of cars	ImvRequest object

Quick Example

Suppose

appId is ali-baba
authToken is open-sesame
you are interested in the single VIN TREASURE for postal code 12345

In that case the URl you want is

https://www.cargurus.com/Cars/api/1.0/imvRequest.action?appId=ali-baba&authToken=open-sesame&body={"listings":[{"vin":"TREASURE","postal_code":"12345"}]}

Note: if crafting a URL by hand, use normal double quotes (") rather than curly or "smart" quotes like “ ”

ImvRequest Fields

Name	Description	Object Type
listings	A list of ImvRequestListing objects, each containing data describing a specific car	Array of ImvRequestListing objects

ImvRequestListing Fields

Name	Description	Object Type
vin	The VIN of the car	string
make	The car's maker name	string
model	The car's model name	string
trim	The car's trim (i.e. LX)	string
year	The year of the car	integer
transmission	The car's transmission (i.e. automatic)	string
mileage	The mileage on the car	integer
options	A comma separated string of available car options	string
is_certified	Whether this car has been certified	boolean (true/false)
price	The price of the car (i.e. 20939)	integer
postal_code	The car dealer's postal code	string
last_updated_timestamp	An ISO-8601 formatted string. Example: '2012-07-04T19:00:00-0700'. Note: Please make sure to include the offset from UTC for your specific time zone (-0700 in the above example).	string

HTTP Response

The API returns a JSON formatted string representing an ImvResponse object described below.

ImvResponse Fields

Name	Description	Object Type
success	Whether the request was processed successfully. This flag describes the overall status of the request. If success is false, then the error object described below will contain the appropriate error code and description.	boolean (true/false)
error	An ApiError object containing a specific error code and description	ApiError object
listings	The list of ImvResponseListing objects, each containing CarGurus Instant Market Value data for the corresponding car.	Array of ImvResponseListing objects

ImvResponseListing Fields

Name	Description	Object Type
success	Whether the car data was processed successfully and the system was able to compute the CarGurus Instant Market Value for the car	boolean (true/false)
error	The ApiError object containing a specific error code and description (see Error Codes below)	ApiError object
vin	The VIN of the car	string
instant_market_value	The car's Instant Market Value	integer
listing_area	CgListingArea object according to the CarGurus ontology	CgListingArea object
cg_make_name	The maker name in the CarGurus ontology	string
cg_model_name	The model name in the CarGurus ontology	string
cg_year	The car's year in the CarGurus ontology	integer
cg_trim_name	The trim name in the CarGurus ontology	string
cg_options	A list of options according to the CarGurus ontology	Array of CgOption objects
cg_entity_id	The car's entity id (internal id used within CarGurus for the specified car)	string
rating	The car's instant market value rating. One of: GREAT_PRICE, GOOD_PRICE, OK_PRICE, NA, FAIR_PRICE, OUTLIER, POOR_PRICE, OVERPRICED If we can't compute the rating for some reason, the rating value returned is NA. If the car's price is outside the expected statistical range, the rating value is set to OUTLIER for that car.	string
rating_boundaries	Contains rating breakdown for the specified car. For details see the RatingBoundaries object description below	RatingBoundaries object
~~comparable_cars~~	Deprecated: A sorted list of ImvComparableCar objects representing similar cars within the same area as the specified car in a typical CarGurus search. The objects in the list are sorted by the "normalized" price for each car, from lowest (best value) to highest (worst value).

CgListingArea Fields

Name	Description	Object Type
city	The name of the city the listing area was built around. If empty, the listing area represents the rural part of the state.	string
state	The name of the city the listing area was built around.	string

CgOption Fields

Name	Description	Object Type
id	The option id in the CarGurus ontology	integer
name	The option's name	string

RatingBoundaries Fields

Name	Description	Object Type
great_price	If the specified car's price is at this value or below, it would have an instant market value of GREAT_PRICE. Note: If the car's price is too low and falls outside of what is statistically acceptable, the car's rating would be OUTLIER.	integer
good_price	If the specified car's price falls in the range between great_price and this value, it would have an instant market value of GOOD_PRICE	integer
fair_price	If the specified car's price falls in the range between good_price and this value, it would have an instant market value of FAIR_PRICE	integer
poor_price	If the specified car's price falls in the range between fair_price and this value, it would have an instant market value of POOR_PRICE. If the car's price is above this value, the car's instant market value will be OVERPRICED. Note: If the car's price is too high and falls outside of what is statistically acceptable, the car's rating would be OUTLIER.	integer

ApiError Fields

Name	Description	Object Type
error_code	The error code	integer
description	The error's description	string

Error Codes

Error codes can be generated at 2 levels:

1. Top level response level. These codes represent problems with the overall processing of the request (10X)

2. Individual listing level - represent issues with computing the instant market value for an individual listings (20X)

Top Level Response Error Codes

100 - bad or malformed request
101 - missing or invalid authentication credentials
102 - invalid application id
103 - I/O error
104 - the rate of requests is too high
105 - unexpected error

Individual Listing Error Codes

200 - couldn't match the requested listing to a specific model in the CarGurus ontology
201 - couldn't match the requested listing to a specific model/year in the CarGurus ontology
202 - the system doesn't have enough data to compute the CarGurus Instant Market Value for the specified car

Examples

Example 1 - (Valid Request)

HTTP Request's 'body' parameter:

  {
      "listings":[
          {
               "vin":"KNDPBCA23B7130388",
               "last_updated_timestamp":"2012-08-29T6:00:16-0700",
               "make":"Kia",
               "model":"Sportage",
               "year":2011,
               "trim":"LX AWD",
               "transmission":"Automatic",
               "mileage":3200,
               "options":"",
               "is_certified":false,
               "price":18000,
               "postal_code":"30909"
          }
      ]
  }

HTTP Response

  {
      "listings":[
          {
               "cg_entity_id": "t38422",
               "cg_make_name": "Kia",
               "cg_model_name": "Sportage",
               "cg_options": [],
               "cg_trim_name": "LX AWD",
               "cg_year": 2011,
               "instant_market_value": 22604,
               "listing_region": "SOUTH_EAST",
               "comparable_cars": [],
               "rating": "GREAT_PRICE",
               "rating_boundaries": {
                  "fair_price": 23889,
                  "good_price": 21319,
                  "great_price": 19859,
                  "poor_price": 25350},
               "success": true,
               "vin": "KNDPBCA23B7130388"
          }
      ],

      "success": true
  }

Example 2 - (Missing or invalid authToken)

HTTP Response

        {
            "error": {
                "description": "Invalid auth credentials.  Details: Invalid auth token",
                 "error_code": 101
            },

            "success": false
        }

Example 3 - (Can't match to a valid model)

HTTP Request's 'body' parameter:

  {
      "listings":[
          {
               "vin":"KNDPBCA23B7130388",
               "last_updated_timestamp":"2012-08-29T6:00:16-0700",
               "make":"BOGUS_MAKER",
               "model":"BOGUS_MODEL",
               "year":2011,
               "trim":"LX AWD",
               "transmission":"Automatic",
               "mileage":3200,
               "options":"",
               "is_certified":false,
               "price":18000,
               "postal_code":"30909"
          }
      ]
  }

HTTP Response

  {
       "listings": [
          {
              "cg_options": [],
              "error": {
                          "description": "Couldn't match the listing data to a known model",
                          "error_code": 200
                       },
              "comparable_cars": [],
              "success": false,
              "vin": ""
           }
        ],
        "success": true
  }

As you can see in the above example, the 'success' flag at the ImvResponse level is set to true because the request was processed successfully. However, the ImvResponseListing's success is false because we couldn't find a match for the model.

Example 4 - (Can't match to a valid model year)

HTTP Request's 'body' parameter:

    {
      "listings":[
        {
          "last_updated_timestamp":"2012-08-29T6:00:16-0700",
          "make":"Kia",
          "model":"Sportage",
          "year":1994,
          "trim":"LX AWD",
          "transmission":"Automatic",
          "mileage":3200,
          "options":"",
          "is_certified":false,
          "price":18000,
          "postal_code":"30909"
        }
      ]
    }

HTTP Response

    {
       "listings":[
          {
             "success":false,
             "error":{
                "error_code":201,
                "description":"Couldn't match the listing data to a known model year"
             },
             "cg_listing_area":{
                "city":"",
                "state":""
             },
             "cg_make_name":"Kia",
             "cg_model_name":"Sportage",
             "cg_entity_id":"d164",
             "cg_options":[],
             "comparable_cars":[]
          }
       ],
       "success":true
    }

Contents

CarGurus Instant Market Value API Documentation

Introduction

HTTP Request

Quick Example

ImvRequest Fields

ImvRequestListing Fields

HTTP Response

ImvResponse Fields

ImvResponseListing Fields

CgListingArea Fields

CgOption Fields

RatingBoundaries Fields

ApiError Fields

Error Codes

Top Level Response Error Codes

Individual Listing Error Codes

Examples

Example 1 - (Valid Request)

HTTP Request's 'body' parameter:

HTTP Response

Example 2 - (Missing or invalid authToken)

HTTP Response

Example 3 - (Can't match to a valid model)

HTTP Request's 'body' parameter:

HTTP Response

Example 4 - (Can't match to a valid model year)

HTTP Request's 'body' parameter:

HTTP Response