Contents

Request Response ApiError Error Codes Examples
Test Console

Filter Values API Documentation

Introduction

This API allows SEM systems to query the site to get valid values for SRP filters.

  • Make a POST to the https://www.cargurus.com/Cars/api/1.0/semFilterValues.action URL specifying the parameters described below
  • Retrieve and process the response which will be a JSON string representing the Response object also described below.

HTTP Request

URL https://www.cargurus.com/Cars/api/1.0/semFilterValues.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 Request object described below which contains the filter name to get valid values for, along with any required parameters (e.g. locale) Request object

Request Body JSON Fields

Name Description Object Type
locale a java locale string for the required country and language. e.g. es_US string
filter_name Name of the filter to iterate values for:
  • colors
  • engine_displacements
  • installed_option_ids
  • engines
  • seatings
  • wheel_systems
 string
entity_id Entity ID of the auto entity to get valid values for string

HTTP Response

The API returns a JSON formatted string representing an Response object described below.

Response 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
possible_values An array of possible values for the given filter. The type of the values depends on the filter. array

ApiError Fields

Name Description Object Type
error_code The error code integer
description The error's description string

Error Codes

  • 100 - the request was invalid

Examples

Example 1 - (Valid Request)

HTTP Request's 'body' parameter:

{
  "locale": "en_US",
  "filter_name": "colors",
  "entity_id": "d2"
}

HTTP Response

{
  "success": true,
  "possible_values": [
    "Red",
    "Silver",
    "Brown",
    "Gold",
    "Gray",
    "White",
    "Pink",
    "Blue",
    "Yellow",
    "Black",
    "Orange",
    "Green"
  ]
}