Contents

Car Selector API Documentation

Introduction

The Car Selector API allows you to build your own used/new listing search widget.
Here are the basic steps for using the API:

1. Create two forms, one for used and one for new. Each form includes: Make select box, Model select box, distance select box and zip code.
2. When displaying a form, populate the make select box and the distance select box with an AJAX call to List Makes Request passing whether this is for new or used.
3. If a make is selected, populate the model select box with an AJAX call to List Models Request passing whether this is for new or used.
4. Finally, when the user submits the form, construct a Listing Search URL passing the selected make/model id and other form values, and have the new URL open in a new window.

Form Field Validation

You are responsible for client side validation of required fields.

	Make	Model	Distance	Zip
Used Search Form	Optional	Optional	Required	Required
New Search Form	Required	Required	Required	Required

List Makes Request

URL	/Cars/api/1.0/carselector/listMakes.action
Method	GET
Parameters	Name Description Object Type searchType Type of search: NEW or USED string

List Makes Response

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 errors will contain a list of issues.	boolean (true/false)
errors	A list of error descriptions	array of string
searchType	Echos back the type of search requested (NEW or USED)	string
makes	List of Entity makes available in alphabetical order	Array of Entity objects
distances	List of Distance objects in ascending order	Array of Distance objects

List Models Request

URL	/Cars/api/1.0/carselector/listModels.action
Method	GET
Parameters	Name Description Object Type searchType Type of search: NEW or USED string makeId Make id as returned from a List Makes Request. string

List Models Response

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 errors will contain a list of issues.	boolean (true/false)
errors	A list of error descriptions	array of string
searchType	Echos back the type of search requested (NEW or USED)	string
makeId	Echos back the id of the make requested	string
models	List of Entity models available in alphabetical order	Array of Entity objects

Response Object Descriptions

Make/Model Entity Fields

Name	Description	Object Type
id	The id of this entity (make or model)	string
name	The display name for this make or model entity (e.g. "Ford" or "Mustang")	string
isPopular	True if this is a popular make or model (in case you want to group entities with popular first)	boolean

Distance Fields

Name	Description	Object Type
value	The distance value (e.g. 50)	integer
display	The display name for this distance (e.g. "50 mi")	string
isDefault	True if this distance should be pre-selected as the default	boolean

Listing Search URL

This is how to construct the URL to which to redirect your user when the invoke a listing search.

URL	/Cars/api/1.0/carselector/listingSearch.action
Method	GET
Parameters	Name Description Object Type searchType Type of search: NEW or USED string entityId Make or Model entity id as selected by the user string postalCode Zip code provided by the user string distance Distance value for the search radius integer affiliatePartner Optional affiliatePartner identifier string

Examples

Example 1 - Request Used Makes

        https://www.cargurus.com/Cars/api/1.0/carselector/listMakes.action?searchType=USED

HTTP Response

      {
        "success":true,
        "searchType":"USED",
        "distances":[{"isDefault":false,"display":"10 mi","value":10},{"isDefault":false,"display":"25 mi","value":25},{"isDefault":false,"display":"50 mi","value":50},{"isDefault":true,"display":"75 mi","value":75},{"isDefault":false,"display":"100 mi","value":100},{"isDefault":false,"display":"150 mi","value":150},{"isDefault":false,"display":"200 mi","value":200},{"isDefault":false,"display":"500 mi","value":500},{"isDefault":false,"display":"Nationwide","value":50000}],
        "makes":[{"name":"Acura","id":"m4","isPopular":true},{"name":"Alfa Romeo","id":"m124","isPopular":false},{"name":"AM General","id":"m79","isPopular":false},{"name":"Aston Martin","id":"m110","isPopular":false},{"name":"Audi","id":"m19","isPopular":true},{"name":"Bentley","id":"m20","isPopular":false},{"name":"BMW","id":"m3","isPopular":true},{"name":"Buick","id":"m21","isPopular":true},{"name":"Cadillac","id":"m22","isPopular":true},{"name":"Chevrolet","id":"m1","isPopular":true},{"name":"Chrysler","id":"m23","isPopular":true},{"name":"Dodge","id":"m24","isPopular":true},{"name":"Ferrari","id":"m25","isPopular":false},{"name":"Fiat","id":"m98","isPopular":true},{"name":"Fisker","id":"m183","isPopular":false},{"name":"Ford","id":"m2","isPopular":true},{"name":"Freightliner","id":"m99","isPopular":false},{"name":"Geo","id":"m83","isPopular":false},{"name":"GMC","id":"m26","isPopular":true},{"name":"Honda","id":"m6","isPopular":true},{"name":"Hummer","id":"m27","isPopular":false},{"name":"Hyundai","id":"m28","isPopular":true},{"name":"Infiniti","id":"m84","isPopular":true},{"name":"Isuzu","id":"m30","isPopular":false},{"name":"Jaguar","id":"m31","isPopular":true},{"name":"Jeep","id":"m32","isPopular":true},{"name":"Kia","id":"m33","isPopular":true},{"name":"Lamborghini","id":"m34","isPopular":false},{"name":"Land Rover","id":"m35","isPopular":true},{"name":"Lexus","id":"m37","isPopular":true},{"name":"Lincoln","id":"m38","isPopular":true},{"name":"Lotus","id":"m39","isPopular":false},{"name":"Maserati","id":"m40","isPopular":true},{"name":"Maybach","id":"m41","isPopular":false},{"name":"Mazda","id":"m42","isPopular":true},{"name":"Mercedes-Benz","id":"m43","isPopular":true},{"name":"Mercury","id":"m44","isPopular":true},{"name":"MG","id":"m102","isPopular":false},{"name":"MINI","id":"m45","isPopular":true},{"name":"Mitsubishi","id":"m46","isPopular":true},{"name":"Nash","id":"m199","isPopular":false},{"name":"Nissan","id":"m12","isPopular":true},{"name":"Oldsmobile","id":"m85","isPopular":false},{"name":"Packard","id":"m176","isPopular":false},{"name":"Panoz","id":"m86","isPopular":false},{"name":"Plymouth","id":"m87","isPopular":false},{"name":"Pontiac","id":"m47","isPopular":true},{"name":"Porsche","id":"m48","isPopular":true},{"name":"Ram","id":"m191","isPopular":true},{"name":"Rolls-Royce","id":"m49","isPopular":false},{"name":"Saab","id":"m50","isPopular":false},{"name":"Saturn","id":"m51","isPopular":true},{"name":"Scion","id":"m52","isPopular":true},{"name":"smart","id":"m111","isPopular":false},{"name":"SRT","id":"m194","isPopular":false},{"name":"Subaru","id":"m53","isPopular":true},{"name":"Suzuki","id":"m54","isPopular":false},{"name":"Tesla","id":"m112","isPopular":false},{"name":"Toyota","id":"m7","isPopular":true},{"name":"Triumph","id":"m137","isPopular":false},{"name":"Vector","id":"m168","isPopular":false},{"name":"Volkswagen","id":"m55","isPopular":true},{"name":"Volvo","id":"m56","isPopular":true}]
      }

Example 2 - Request Used Volkswagen Models

        https://www.cargurus.com/Cars/api/1.0/carselector/listModels.action?searchType=USED&makeId=m55

HTTP Response

      {
        "success":true,
        "searchType":"USED",
        "makeId":"m55",
        "models":[{"name":"Beetle","id":"d201","isPopular":true},{"name":"Cabrio","id":"d193","isPopular":false},{"name":"CC","id":"d2014","isPopular":true},{"name":"e-Golf","id":"d2284","isPopular":true},{"name":"Eos","id":"d915","isPopular":true},{"name":"EuroVan","id":"d196","isPopular":false},{"name":"GLI","id":"d1519","isPopular":false},{"name":"Golf","id":"d198","isPopular":true},{"name":"Golf R","id":"d2131","isPopular":true},{"name":"Golf SportWagen","id":"d2307","isPopular":true},{"name":"GTI","id":"d199","isPopular":true},{"name":"Jetta","id":"d200","isPopular":true},{"name":"Jetta SportWagen","id":"d2094","isPopular":false},{"name":"Passat","id":"d202","isPopular":true},{"name":"Phaeton","id":"d203","isPopular":false},{"name":"R32","id":"d204","isPopular":false},{"name":"Rabbit","id":"d839","isPopular":false},{"name":"Routan","id":"d1522","isPopular":false},{"name":"Tiguan","id":"d1104","isPopular":true},{"name":"Touareg","id":"d205","isPopular":true},{"name":"Touareg 2","id":"d1045","isPopular":false}]
      }

Example 2 - Generated Used Volkswagen Model Search

        https://www.cargurus.com/Cars/api/1.0/carselector/listingSearch.action?searchType=USED&entityId=m55&postalCode=02144&distance=50