Contents

Dealer Stats With Vins API Documentation Version 2.0

Introduction

The Dealer Stats API enables your application to retrieve the statistics related to your inventory.
This API is available both for Partner level and for Dealer level.
Here are the basic steps for using the API:

• Make a POST to the https://www.cargurus.com/Cars/api/2.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/2.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	Notes
external_dealer_id	The dealer's external id	String	Required if it is a partner level request. Not required if it is a dealer level request
start_date	The start date	Date	The date is inclusive
end_date	The end date	Date	The date is inclusive.The end date can not be more than 6 months from the start 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
vin_stats	The list of VinStats objects, each containing stats for a specific vin.	Array of VinStats objects

VinStats Fields

Name	Description	Object Type
vin	car vin number	string
printouts	The total number of printed dealer maps/address instructions for the date range specified	Integer
vdps	The total number of vehicle detail page views for the date range specified	Integer
srps	The total number of search result page views for the date range specified	Integer
chat_leads	The total number of leads chats for the date range specified	Integer
sms_leads	The total number of lead sms for the date range specified	Integer
phone_leads	The total number of phone leads for the requested vin for the date range specified. This number excludes phone leads to phone numbers not associated with a specific VIN	Integer
email_leads	The total number of leads emails for the date range specified	Integer
twitter_clicks	The total number of twitter clicks for the date range specified	Integer
facebook_clicks	The total number of facebook clicks for the date range specified	Integer
website_clicks	The total number of website clicks for the date range specified	Integer
map_clicks	The total number of map clicks for the date range specified	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
• 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" : "myusedcarcenter",
          "start_date" : "2013-10-14",
          "end_date" : "2013-10-16"
      }

HTTP Response

      {
           "vin_stats": [
                {
                     "phone_leads": 38,
                     "twitter_clicks": 19,
                     "printouts": 11,
                     "srps": 200,
                     "vdps": 213,
                     "chat_leads": 44,
                     "leads_email": 67,
                     "map_clicks": 23,
                     "sms_leads": 3,
                     "vin": "1FMCU0GX3EUC76848",
                     "facebook_clicks": 33,
                     "website_clicks": 46
                },
                {
                     "phone_leads": 88,
                     "twitter_clicks": 77,
                     "printouts": 5,
                     "srps": 99,
                     "vdps": 76,
                     "chat_leads": 89,
                     "leads_email": 67,
                     "map_clicks": 34,
                     "sms_leads": 12,
                     "vin": "1J4FY19S4WP704453",
                     "facebook_clicks": 2,
                     "website_clicks": 4
                }
           ],
           "success": true
      }

Example 2 - (Missing or invalid authToken)

HTTP Response

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

          "success": false
      }