Dealer Reviews API Documentation
Introduction
The Dealer Reviews API enables your application to retrieve the reviews for a particular dealer.
These reviews are primarily for internal use by the requested dealership.
However, the reviews can be shared on the dealer's website or via social media under the following conditions:
- No more than 160 characters of any particular review should be included.
-
Any external use must include:
- A link to the full review on CarGurus
- A credit to CarGurus as the source
Here are the basic steps for using the API:
- Make a POST to the https://www.cargurus.com/Cars/api/1.0/dealerReviewsRequest.action URL specifying the parameters described below
- Retrieve and process the response which will be a JSON string representing the DealerReviewsResponse object also described below.
HTTP Request
| URL |
https://www.cargurus.com/Cars/api/1.0/dealerReviewsRequest.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 DealerReviewsRequest object described below |
DealerReviewsRequest object |
|
DealerReviewsRequest Fields
HTTP Response
The API returns a JSON formatted string representing an DealerReviewsResponse object described below.
DealerReviewsResponse 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 |
| dealer |
Dealer object containing basic information about the requested dealer. |
Dealer |
| manage_reviews_url |
The url for this dealer's CarGurus review management dashboard.
The dealer will need to contact CarGurus support for a free account. |
String |
| reviews |
The list of Review objects, each containing information about a particular user sales review. |
Array of Review objects |
Dealer Fields
| Name |
Description |
Object Type |
| id |
The id of this dealer. Will match the dealer_id field from the DealerReviewsRequest. |
String |
| name |
Name of the dealership |
String |
| url |
The dealers CarGurus URL. This pre-selects the reviews tab on this page. |
String |
Review Fields
| Name |
Description |
Object Type |
| id |
The unique id of this review. |
String |
| url |
The review's CarGurus URL. This pre-selects the reviews tab and moves this review to the top. |
String |
| rating |
The user's rating of this dealership. Possible values of 1-5. |
Integer |
| author |
Display name for the review's author. |
String |
| body |
The written portion of the user's review. |
String |
| status |
One of the following values:
| UNDER_REVIEW |
User has submitted the review, but it has not yet passed editorial review.
The review is visible on the site during this period. |
| APPROVED |
The review has passed editorial review. |
|
String |
| creation_timestamp |
When the user first submitted the review. Example: 2015-06-22 22:30 |
Timestamp |
| last_update_timestamp |
When the review was last updated (approved by an editor or modified by the user). Example: 2015-07-02 09:02 |
Timestamp |
| management_response |
Optional ManagementResponse object containing a response to this review
provided by the dealership. |
ManagementResponse |
ManagementResponse Fields
| Name |
Description |
Object Type |
| response |
The written response from the dealer. |
String |
| creation_timestamp |
When the management response was first submitted the review. Example: 2015-06-22 22:30 |
Timestamp |
| status |
One of the following values:
| UNDER_REVIEW |
Dealership has submitted the response, but it has not yet passed editorial review.
The review is not visible on the site during this period. |
| APPROVED |
The response has passed editorial review and is now visible on CarGurus. |
|
String |
ApiError Fields
| Name |
Description |
Object Type |
| error_code |
The error code |
integer |
| description |
The error's description |
string |
Error Codes
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
- 108 - invalid dealer
Examples
Example 1 - (Valid Request)
HTTP Request's 'body' parameter:
{
"dealer_id" : "sp284739"
}
HTTP Response
{
"reviews": [
{
"last_update_timestamp": "2014-05-26 10:40",
"creation_timestamp": "2014-05-26 10:40",
"author": "Jose",
"rating": 4,
"id": "dr242430",
"url": "https://cargur.us/3Tb3T",
"body": "They were prompt in servicing me for my search I'm just not ready for purshase",
"status": "UNDER_REVIEW"
},
{
"last_update_timestamp": "2014-05-15 12:03",
"creation_timestamp": "2014-05-15 10:41",
"author": "Pat",
"rating": 5,
"id": "dr236730",
"url": "https://cargur.us/3Tb5p",
"body": "Dealer responded promptly. Unfortunately for me the vehicle had just been sold.",
"status" : APPROVED"
},
],
"manage_reviews_url": "https://www.cargurus.com/Cars/dealerdashboard/selfservice/manageSalesReviews.action?serviceProvider=sp284739",
"success": true,
"dealer": {
"name": "Emmons Motor Company",
"id": "sp284739",
"url": "https://www.cargurus.com/Cars/m-Emmons-Motor-Company-sp284739"
}
}
Example 2 - (Missing or invalid authToken)
HTTP Response
{
"success": false,
"error": {
"description": "Invalid auth credentials. Details: Invalid auth token",
"error_code": 101
}
}