Contents

Dealer Stats API Documentation Version 1.0 (Deprecated)

Introduction

The Dealer Stats API enables your application to retrieve the statistics related to your inventory.
Here are the basic steps for using the API:

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

HTTP Request

URL	https://www.cargurus.com/Cars/api/1.0/dealerStatsRequest.action
Method	POST
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 DealerStatsRequest object described below DealerStatsRequest object

DealerStatsRequest Fields

Name	Description	Object Type
external_dealer_id	The dealer's external id	String
start_date	The start date	Date
end_date	The end date	Date

HTTP Response

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

DealerStatsResponse 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
daily_stats	The list of DailyStats objects, each containing stats for a specific day.	Array of DailyStats objects
total_impressions	The total number of matching searches for the date range specified	Integer
total_clicks	The total number of clicks for the date range specified	Integer
total_leads	The total number of leads for the date range specified.	Integer

DailyStats Fields

Name	Description	Object Type
date	The date for the stats contained within this object	Date
impressions	The number of matching searches for the day	integer
clicks	The number of clicks for the day	integer
leads	The number of leads for the day	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:

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:

      {
          "external_dealer_id" : "tomsmithtradeincenter",
          "start_date" : "2013-10-14",
          "end_date" : "2013-10-15"
      }

HTTP Response

      {      "daily_stats": [
                {
                   "clicks": 50,
                   "date": "2013-10-15",
                   "impressions": 1106,
                   "leads": 0
                },
                {
                   "clicks": 70,
                   "date": "2013-10-14",
                   "impressions": 1194,
                   "leads": 1
                }
              ],
              "success": true,
              "total_clicks": 120,
              "total_impressions": 2300,
              "total_leads": 1
      }

Example 2 - (Missing or invalid authToken)

HTTP Response

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

          "success": false
      }