SEM Ad Landing URL API Documentation
Introduction
This API allows SEM systems to query the site to get URLs generated according to the
current URL conventions.
- Make a POST to the https://www.cargurus.com/Cars/api/1.0/semUrlGenerator.action URL specifying the parameters described below
- Retrieve and process the response which will be a JSON string representing the SemUrlResponse object also described below.
HTTP Request
| URL |
https://www.cargurus.com/Cars/api/1.0/semUrlGenerator.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 SemUrlRequest object described below which contains the type of landing url to generate along with any required parameters (e.g. locale) |
SemUrlRequest object |
|
SemUrlRequest Body JSON Fields
| Name |
Description |
Object Type |
| url_type |
|
string |
| locale |
a java locale string for the required country and language. e.g. es_US. Required/valid for all url_type's |
string |
| parameters |
Used by NEW_CAR and USED_CAR SRP URLs to filter results
| Name |
Object Type |
Description |
| min_price |
long |
| max_price |
long |
| min_mileage |
long |
| max_mileage |
long |
| min_co2_emission |
long |
| max_co2_emission |
long |
| location_id |
long |
| start_year |
integer |
| end_year |
integer |
| min_mpg |
integer |
| max_mpg |
integer |
| min_engine_displacement |
double |
| max_engine_displacement |
double |
| days_on_market_min |
short |
| days_on_market_max |
short |
| latitude |
float |
| longitude |
float |
| hide_fleet |
boolean |
| hide_frame_damage |
boolean |
| hide_lemon |
boolean |
| hide_multiple_owners |
boolean |
| hide_salvage |
boolean |
| hide_theft |
boolean |
| hide_without_photos |
boolean |
| is_automatic_transmission |
boolean |
| price_drops_only |
boolean |
| entity_id |
string |
| locale |
string |
| zip |
string |
| distance |
string |
| engine_displacements |
array of strings |
Valid values can be enumerated with the Filter Values API |
| new_used_criteria |
array of integers |
1 = NEW
2 = USED
3 = CPO |
| seatings |
array of integers |
Valid values can be enumerated with the Filter Values API |
| wheel_systems |
array of strings |
Valid values can be enumerated with the Filter Values API |
| body_styles |
array of longs |
| installed_option_ids |
array of longs |
Valid values can be enumerated with the Filter Values API |
| colors |
array of strings |
external color
Valid values can be enumerated with the Filter Values API |
| engines |
array of strings |
Valid values can be enumerated with the Filter Values API |
| seller_types |
array of strings:'PRIVATE' or 'DEALER' |
| advanced_search_auto_entities |
array of strings |
|
object |
HTTP Response
The API returns a JSON formatted string representing an SemUrlResponse object described below.
SemUrlResponse 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 |
| url |
The landing url for the given request |
string |
ApiError Fields
| Name |
Description |
Object Type |
| error_code |
The error code |
integer |
| description |
The error's description |
string |
Error Codes
- 101 - the locale given on the request is not yet implemented or is invalid
- 102 - the given request data is valid, but the system was unable to generate an url
- 103 - the given entity id was not able to be found in the database
- 104 - the given location id was not able to be found in the database
- 105 - the given data items in the request are not supported. e.g. cheap cars url given a specific entity id
Examples
Example 1 - (Valid Request)
HTTP Request's 'body' parameter:
{
"url_type": "CHEAP_USED_CARS",
"locale": "en_US"
}
HTTP Response
{
"success": true,
"url": "https://www.cargurus.com/Cars/spt-cheap-cars"
}
Example 2 - (Request with Parameters)
HTTP Request's 'body' parameter:
{
"url_type": "USED_CAR",
"locale": "en_US",
"parameters":
{
"location_id": 5
}
}
HTTP Response
{
"success":true,
"url":"https://www.cargurus.com/Cars/spt-used-cars-Jefferson_L5"
}
Example 3 - (Invalid Request)
HTTP Request's 'body' parameter:
{
"url_type": "CHEAP_USED_CARS",
"locale": "fr_US"
}
HTTP Response
{
"success": false,
"error":
{
"description": "Unsupported application locale fr_US",
"error_code": 101
}
}
Example 4 - (Valid Request)
HTTP Request's 'body' parameter:
{
"url_type": "SEO_PAGE_TYPE",
"seo_page_type": "spt-cheap-cars"
"locale": "en_US"
}
HTTP Response
{
"success": true,
"url": "https://www.cargurus.com/Cars/spt-cheap-cars"
}