Dealer Stats With SEM Plus 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 |
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 SemPlusStats objects, each containing stats for a specific day. |
Array of SemPlusStats objects |
| impressions_total |
The total number of impressions for the date range specified |
Integer |
| clicks_total |
The total number of clicks for the date range specified |
Integer |
| search_views_total |
The total number of search views for the date range specified |
Integer |
| detail_views_total |
The total number of detail views for the date range specified |
Integer |
| key_page_views_total |
The total number of key page views for the date range specified |
Integer |
| map_views_total |
The total number of map views for the date range specified |
Integer |
| web_leads_total |
The total number of web leads for the date range specified |
Integer |
| phone_leads_total |
The total number of phone leads for the date range specified |
Integer |
| cost_total |
The total cost for the date range specified |
Number |
SemPlusStats Fields
| Name |
Description |
Object Type |
| date |
The date for the stats contained within this object |
Date |
| partner |
The SEM partner for the stats contained within this object |
String |
| campaign |
The campaign for the stats contained within this object |
String |
| campaign_type |
The campaign type (New/Used) for the stats contained within this object |
String |
| device_type |
The device type (Mobile/Desktop) for the stats contained within this object |
String |
| impressions |
The number of impressions for this stats object |
Integer |
| clicks |
The number of clicks for this stats object |
Integer |
| search_views |
The number of search views for this stats object |
Integer |
| detail_views |
The number of detail views for this stats object |
Integer |
| key_page_views |
The number of key page views for this stats object |
Integer |
| map_views |
The number of map views for this stats object |
Integer |
| web_leads |
The number of web leads for this stats object |
Integer |
| phone_leads |
The number of phone leads for this stats object |
Integer |
| cost |
The total cost for this stats object |
Number |
ApiError Fields
| Name |
Description |
Object Type |
| error_code |
The error code |
integer |
| description |
The error's description |
string |
Error Codes
These codes represent problems with the overall processing of the request (10X)
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
Examples
Example 1 - (Valid Request)
HTTP Request's 'body' parameter:
{
"external_dealer_id" : "myusedcarcenter",
"start_date" : "2017-01-20",
"end_date" : "2017-01-22"
}
HTTP Response
{
"success": true,
"impressions_total": 5700,
"clicks_total": 111,
"search_views_total": 280,
"detail_views_total": 157,
"key_page_views_total": 5,
"map_views_total": 1,
"web_leads_total": 0,
"phone_leads_total": 1,
"cost_total": 220.93,
"daily_stats": [
{
"date": "2017-01-20",
"phone_leads": 0,
"cost": 0,
"campaign_type": "Used",
"search_views": 0,
"device_type": "Mobile",
"web_leads": 0,
"impressions": 1,
"map_views": 0,
"partner": "Google",
"campaign": "Mercedes-Benz GLK-Class",
"clicks": 0,
"key_page_views": 0,
"detail_views": 0
},
{
"date": "2017-01-20",
"phone_leads": 0,
"cost": 1.49,
"campaign_type": "Used",
"search_views": 1,
"device_type": "Mobile",
"web_leads": 0,
"impressions": 28,
"map_views": 0,
"partner": "Google",
"campaign": "No Maker",
"clicks": 1,
"key_page_views": 0,
"detail_views": 0
},
{
"date": "2017-01-22",
"phone_leads": 0,
"cost": 0,
"campaign_type": "Used",
"search_views": 0,
"device_type": "Desktop",
"web_leads": 0,
"impressions": 2,
"map_views": 0,
"partner": "Google",
"campaign": "2015 Mercedes-Benz GL-Class",
"clicks": 0,
"key_page_views": 0,
"detail_views": 0
}
]
}
Example 2 - (Missing or invalid authToken)
HTTP Response
{
"error": {
"description": "Invalid auth credentials. Details: Invalid auth token",
"error_code": 101
},
"success": false
}