---
title: "Find similar published listings"
method: GET
path: "/v1/vehicles/{listing_id}/similar"
tags: ["Vehicles"]
---

# Find similar published listings

`GET /v1/vehicles/{listing_id}/similar`

## Request

- Base URL: `https://api.carhandshake.com`
- URL: `https://api.carhandshake.com/v1/vehicles/{listing_id}/similar`
- Auth: none required

## Path parameters

- `listing_id` string, uuid, required

## Query parameters

- `limit` integer

## Response `200`

Similar listings

- SearchResponse
  - `items` VehicleListingSummary[], required
    - `canonical_attributes` object
    - `canonical_features` object[]
      - `id` 'apple_carplay' | 'android_auto' | 'backup_camera' | 'blind_spot_warning' | 'forward_aeb' | 'rear_cross_traffic_warning' | 'heated_front_seats' | 'adaptive_cruise_control' | 'lane_keep_assist' | 'bluetooth_audio' | 'remote_start' | 'third_row_seating' | 'sunroof' | 'parking_sensors' | 'leather_seating' | 'ventilated_front_seats' | 'heated_steering_wheel' | 'proximity_keyless_entry' | 'push_button_start' | 'power_liftgate' | 'panoramic_glass_roof' | 'driver_seat_memory' | 'power_driver_seat' | 'power_passenger_seat' | 'built_in_navigation' | 'wireless_phone_charging' | 'premium_audio' | 'lane_departure_warning' | 'surround_view_camera' | 'automatic_high_beams' | 'automatic_climate_control' | 'led_headlights' | 'heated_rear_seats' | 'second_row_captains_chairs' | 'trailer_hitch' | 'towing_package' | 'trailer_brake_controller' | 'forward_collision_warning' | 'rear_aeb' | 'lane_centering_assist' | 'pedestrian_aeb' | 'blind_spot_camera' | 'head_up_display' | 'active_parking_assist' | 'power_sliding_doors' | 'synthetic_leather_seating' | 'dc_fast_charging' | 'heat_pump' | 'battery_preconditioning' | 'vehicle_to_load', required
      - `state` 'present', required
      - `qualifiers` object
        - `connection` 'wired' | 'wireless'
        - `position` 'front' | 'rear' | 'front_and_rear'
        - `stop_and_go` boolean
        - `hands_free` boolean
      - `qualifier_facts` object[]
        - `state` 'present' | 'absent' | 'unknown' | 'conflicted' | 'not_applicable', required
        - `qualifiers` object, required
          - `connection` 'wired' | 'wireless'
          - `position` 'front' | 'rear' | 'front_and_rear'
          - `stop_and_go` boolean
          - `hands_free` boolean
    - `feature_ids` string[]
    - `taxonomy_version` string
    - `normalizer_version` string
    - `quality` object
      - `version` 1, required
      - `price` object, required
        - `known` boolean, required
        - `review_reasons` string[], required
      - `photos` object, required
        - `usable_count` integer, required
      - `observation` object, required
        - `inventory_observed_at` string, date-time, nullable, required
        - `record_updated_at` string, date-time, nullable, required
        - `seller_confirmed_at` unknown, required
      - `identity` object, required
        - `status` 'resolved' | 'unconfirmed', required
      - `specifications` object, required
        - `conflicting_fields` string[], nullable, required
      - `physical_lot` object, required
        - `resolved` boolean, required
      - `homepage` object, required
        - `eligible` boolean, required
        - `reasons` string[], required
    - `listing_id` string, uuid, required
    - `vin` string, required
    - `stock` string, nullable, required
    - `year` integer, required
    - `make` string, required
    - `model` string, required
    - `trim` string, nullable, required
    - `vehicle_type` 'car' | 'motorcycle' | 'trailer' | 'rv' | 'other', required
    - `displacement_cc` number, nullable, required
    - `battery_kwh` number, nullable, required
    - `motor_power_hp` number, nullable, required
    - `dc_fast_charge` boolean, nullable, required
    - `charge_port` string, nullable, required
    - `condition` 'new' | 'used' | 'cpo' | 'null', nullable, required
    - `body` string, nullable, required
    - `fuel` string, nullable, required
    - `driveline` string, nullable, required
    - `transmission` string, nullable, required
    - `exterior_color` string, nullable, required
    - `interior_color` string, nullable, required
    - `price` integer, nullable, required: Current advertised amount in the listing currency (USD for US, CAD for CA), or null when omitted.
    - `msrp` integer, nullable, required: USD for US listings; CAD for Canadian listings.
    - `currency` 'USD' | 'CAD', required: Required to match location.country: USD for US and CAD for CA.
    - `mileage` integer, nullable, required: Miles for US listings; kilometres for Canadian listings.
    - `electric_range_miles` number, nullable, required: Miles for US listings; kilometres for Canadian listings. Wire name retained for compatibility.
    - `status` 'available' | 'intransit', required
    - `primary_photo_url` string, uri, nullable, required
    - `updated_at` string, date-time, required: Catalog record update time; not seller confirmation or inventory observation. Optional quality.observation distinguishes those facts.
    - `distance_miles` number, nullable, required: Miles for a US search or kilometres for a Canadian search; wire name retained for compatibility.
    - `dealer` PublicDealer, required
      - `id` string, uuid, required
      - `name` string, required
      - `domain` string, required
      - `agent_card_url` string, uri
      - `a2a_url` string, uri
    - `location` PublicLocation, required
      - `id` string, uuid, required
      - `name` string, required
      - `address_line_1` string, nullable, required
      - `address_line_2` string, nullable, required
      - `city` string, nullable, required
      - `state` string, nullable, required
      - `zip` string, nullable, required
      - `country` 'US' | 'CA', required
      - `latitude` number, nullable, required
      - `longitude` number, nullable, required
      - `geo_source` string, nullable, required
      - `geocode_precision` string, nullable, required
      - `geocode_confidence` number, nullable, required
      - `timezone` string, nullable, required
      - `website_url` string, uri, nullable, required
      - `public_phone` PublicPhone, required
        - `name` string, nullable, required
        - `value` string, required
      - `hours` BusinessHoursSchedule[], required
        - `name` string, required
        - `monday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
        - `tuesday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
        - `wednesday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
        - `thursday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
        - `friday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
        - `saturday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
        - `sunday` BusinessHoursInterval
          - `open` string, required
          - `close` string, required
      - `capabilities` string[], required
    - `canonical_url` string, uri, nullable, required: Canonical Car Handshake VDP URL when website publication is permitted.
    - `dealer_vdp_url` string, uri, nullable, required
  - `facets` object, required
  - `map` MapClusterResult
    - `zoom` integer, required
    - `truncated` boolean, required: True when more than 500 occupied map tiles matched the search.
    - `clusters` object[], required
      - `id` string, required
      - `center` object, required
        - `latitude` number, required
        - `longitude` number, required
      - `count` integer, required
      - `bounds` GeoBounds, required: Bounds of the listing coordinates represented by a map cluster.
        - `north` number, required
        - `south` number, required
        - `east` number, required
        - `west` number, required
  - `total` object, required
    - `value` integer, required
    - `relation` 'eq' | 'gte', required
  - `next_cursor` string, nullable, required
  - `interpreted_query` object, required
    - `original` string, nullable, required
    - `assumptions` string[], required
    - `location` object, nullable, required
      - `label` string, required
      - `confidence` number, required
      - `latitude` number, required
      - `longitude` number, required
  - `applied_filters` SearchFilters, required
    - `identity_predicates` object[]
      - `attribute` 'make' | 'model' | 'trim', required
      - `alternatives` object[], required
        - `id` string, required
        - `scope` object
          - `countries` string[], required
          - `vehicle_types` string[], required
          - `year_min` integer, required
          - `year_max` integer, required
    - `feature_predicates` object[]
      - `id` 'apple_carplay' | 'android_auto' | 'backup_camera' | 'blind_spot_warning' | 'forward_aeb' | 'rear_cross_traffic_warning' | 'heated_front_seats' | 'adaptive_cruise_control' | 'lane_keep_assist' | 'bluetooth_audio' | 'remote_start' | 'third_row_seating' | 'sunroof' | 'parking_sensors' | 'leather_seating' | 'ventilated_front_seats' | 'heated_steering_wheel' | 'proximity_keyless_entry' | 'push_button_start' | 'power_liftgate' | 'panoramic_glass_roof' | 'driver_seat_memory' | 'power_driver_seat' | 'power_passenger_seat' | 'built_in_navigation' | 'wireless_phone_charging' | 'premium_audio' | 'lane_departure_warning' | 'surround_view_camera' | 'automatic_high_beams' | 'automatic_climate_control' | 'led_headlights' | 'heated_rear_seats' | 'second_row_captains_chairs' | 'trailer_hitch' | 'towing_package' | 'trailer_brake_controller' | 'forward_collision_warning' | 'rear_aeb' | 'lane_centering_assist' | 'pedestrian_aeb' | 'blind_spot_camera' | 'head_up_display' | 'active_parking_assist' | 'power_sliding_doors' | 'synthetic_leather_seating' | 'dc_fast_charging' | 'heat_pump' | 'battery_preconditioning' | 'vehicle_to_load', required
      - `qualifiers` object
        - `connection` 'wired' | 'wireless'
        - `position` 'front' | 'rear' | 'front_and_rear'
        - `stop_and_go` boolean
        - `hands_free` boolean
    - `transmission_predicates` object[]
      - `id` 'automatic' | 'manual', required
      - `mechanism` 'conventional_automatic' | 'cvt' | 'ecvt' | 'dual_clutch' | 'automated_manual' | 'single_speed' | 'manual'
      - `forward_gears` integer
    - `attribute_predicates` union[]
      - union
        - object
          - `attribute` 'body', required
          - `id` string, required
          - `details` object, required
            - `doors` integer
            - `cab_type` 'crew' | 'extended' | 'regular'
        - object
          - `attribute` 'fuel', required
          - `id` string, required
          - `details` object, required
            - `energy_carriers` string[]
            - `architecture` 'ice' | 'hybrid' | 'mild_hybrid' | 'phev' | 'bev' | 'fuel_cell'
            - `plug_in` boolean
    - `vehicle_types` string[]
    - `makes` string[]
    - `models` string[]
    - `trims` string[]
    - `conditions` string[]
    - `bodies` string[]
    - `fuels` string[]
    - `drivelines` string[]
    - `transmissions` string[]
    - `exterior_colors` string[]
    - `interior_colors` string[]
    - `features` string[]
    - `dealer_ids` string[]
    - `year_min` integer
    - `year_max` integer
    - `price_min` integer
    - `price_max` integer
    - `has_price` boolean
    - `mileage_max` integer: Miles for US searches; kilometres for Canadian searches.
    - `seats_min` integer
    - `seats_max` integer
    - `doors_min` integer
    - `doors_max` integer
    - `city_mpg_min` integer
    - `highway_mpg_min` integer
    - `displacement_cc_min` integer
    - `displacement_cc_max` integer
    - `electric_range_min` number: Miles for US searches; kilometres for Canadian searches.
    - `electric_range_max` number: Miles for US searches; kilometres for Canadian searches.
    - `dc_fast_charge` boolean
    - `charge_ports` string[]
    - `delivery_available` boolean
    - `statuses` string[]
  - `applied_spec` SearchSpec
    - `version` 2, required
    - `market` object, required
      - `country` 'US' | 'CA', required
      - `currency` 'USD' | 'CAD', required
      - `distance_unit` 'mi' | 'km', required
    - `required` union[], required
      - union
        - object
          - `field` 'vehicle_type', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'condition', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'body', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'fuel', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'driveline', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'transmission', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'identity', required
          - `operator` 'any_of', required
          - `alternatives` object[], required
            - `make` string, required
            - `model` string
            - `trim` string
        - object
          - `field` 'feature', required
          - `operator` 'all_of' | 'none_of', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'year', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'year', required
        - object
          - `field` 'price', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'USD' | 'CAD', required
        - object
          - `field` 'mileage', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` number, required
          - `unit` 'mi' | 'km', required
        - object
          - `field` 'seats', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'count', required
        - object
          - `field` 'doors', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'count', required
        - object
          - `field` 'electric_range', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` number, required
          - `unit` 'mi' | 'km', required
    - `preferred` union[], required
      - union
        - object
          - `field` 'vehicle_type', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'condition', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'body', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'fuel', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'driveline', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'transmission', required
          - `operator` 'in' | 'not_in', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'identity', required
          - `operator` 'any_of', required
          - `alternatives` object[], required
            - `make` string, required
            - `model` string
            - `trim` string
        - object
          - `field` 'feature', required
          - `operator` 'all_of' | 'none_of', required
          - `values` string[], required
          - `unknown` 'exclude', required
        - object
          - `field` 'year', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'year', required
        - object
          - `field` 'price', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'USD' | 'CAD', required
        - object
          - `field` 'mileage', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` number, required
          - `unit` 'mi' | 'km', required
        - object
          - `field` 'seats', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'count', required
        - object
          - `field` 'doors', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` integer, required
          - `unit` 'count', required
        - object
          - `field` 'electric_range', required
          - `operator` 'eq' | 'lt' | 'lte' | 'gt' | 'gte', required
          - `value` number, required
          - `unit` 'mi' | 'km', required
    - `location` union, required
      - object
        - `kind` 'market', required
      - object
        - `kind` 'nationwide', required
        - `explicit` true, required
      - object
        - `kind` 'postal', required
        - `postal_code` string, required
        - `radius` object, required
          - `value` number, required
          - `unit` 'mi' | 'km', required
      - object
        - `kind` 'place', required
        - `place_name` string, required
        - `region_code` string, required
        - `radius` object, required
          - `value` number, required
          - `unit` 'mi' | 'km', required
      - object
        - `kind` 'region', required
        - `region_code` string, required
      - object
        - `kind` 'unresolved', required
        - `input` string, required
        - `radius` object
          - `value` number, required
          - `unit` 'mi' | 'km', required
    - `residual` object[], required
      - `text` string, required
      - `status` 'text_match' | 'unresolved', required
    - `sort` object, required
      - `by` 'relevance' | 'distance' | 'price' | 'mileage' | 'year' | 'freshness', required
      - `direction` 'asc' | 'desc'
  - `suggested_relaxations` object[], required
    - `action` 'expand_radius' | 'remove_filter' | 'search_nationwide', required
    - `field` string, required
    - `suggestion` string, required
  - `coverage` object, required
    - `country` 'US' | 'CA', required
    - `mode` 'radius' | 'region' | 'viewport' | 'nationwide', required
    - `radius_miles` number, nullable, required: Miles for US coverage or kilometres for Canadian coverage; wire name retained for compatibility.
    - `region_code` string, nullable
  - `freshness` object, required
    - `catalog_snapshot_at` string, date-time, required
    - `newest_listing_updated_at` string, date-time, nullable, required
  - `request_id` string, required
  - `index_timestamp` string, date-time, required

## Other responses

- `404`: RFC 9457 problem details

---

[API](https://skmtc.dev/carhandshake/apis/car-handshake-inventory-api.md) · [All operations](https://skmtc.dev/carhandshake/apis/car-handshake-inventory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carhandshake/apis/car-handshake-inventory-api/revisions/0a85bfd1c565?raw)