# Inventory Search > Search active dealer heavy equipment listings currently for sale in US markets with comprehensive filtering, sorting, analytics, and geographic targeting capabilities for heavy equipment. > **WARNING**: > **Limited Support Warning**: Heavy Equipment APIs is maintained less frequently than our primary cars dataset, with reduced priority and support. Data quality, coverage, and feature updates may be less comprehensive and occur less often than in our core automotive offerings. The Heavy Equipment Inventory Search API provides access to active heavy equipment listings from dealers across the US markets. This comprehensive search tool enables heavy equipment dealers, marketplaces, and consumers to discover, filter, and analyze heavy equipment with sophisticated filtering capabilities designed specifically for the heavy equipment industry. Whether you're building heavy equipment marketplace applications, dealer inventory systems, or consumer search tools, this API delivers the specialized functionality needed for heavy equipment applications with extensive parameter options covering equipment-specific features like category types, operating hours, engine specifications, and weight ratings. ## Overview - Access active dealer heavy equipment inventory across US markets with thousands of listings - Data updates published regularly for current market conditions - Comprehensive filtering with 50+ parameters specific to heavy equipment **Units & Conventions:** | Field / Pattern | Unit | Notes | |-----------------|-----------------|-----------------| | price, msrp | USD (US) | Applies to all price-like currency fields | | miles, radius, dist | Miles | Applies to both markets in request as well as response | | *_at | Unix epoch seconds (UTC) | Applies to all timestamp fields (e.g. `last_seen_at`) | | *_at_date | ISO-8601 `YYYY-MM-DDThh:mm:ssZ` (UTC) | Same instant as the matching *_at field | ## Base Path ```http GET https://api.marketcheck.com/v2/search/heavy-equipment/active ``` The following example demonstrates a basic search request with common parameters: ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` Explore the full range of parameters available for filtering, sorting, and configuring search results in the [Parameters](#parameters) section below. ## Request The Heavy Equipment Inventory Search API provides extensive filtering and search capabilities for heavy equipment listings. You can search by equipment specifications, geographic location, pricing ranges, dealer types, and numerous other criteria to find the exact equipment you need. ### Parameters Available parameters for filtering, sorting, and configuring search results: | Parameter | Type | Required | Description | |-------------|-------------|-------------|-------------| | `api_key` | string | Yes | Your MarketCheck API authentication key. Required for every request, unless OAuth is used. | | `body_type` | string | No | Filters listings by body type (e.g., SUV, Pickup, Sedan, Hatchback, Convertible). Accepts multiple values separated by commas. | | `category` | string | No | Filters listings by Heavy Equipment category (e.g. `Agriculture`, `Construction`, `Crane`). Accepts multiple categories as comma-separated values. | | `city` | string | No | Filters listings by city name (e.g. `Los Angeles`, `San Francisco`, `Houston`). | | `dealer_id` | string | No | Filters listings by MarketCheck dealer ID. | | `dealer_name` | string | No | Filters listings by dealer name (case-insensitive complete match, substring not supported). | | `drivetrain` | string | No | Filters listings by drivetrain (`FWD`, `RWD`, `4WD`). Accepts multiple values separated by commas. | | `engine` | string | No | Filters listings by engine designation (e.g., `2.0L I4`, `3.5L V6`, `2.5L H4`). Accepts multiple values as comma-separated list. | | `exterior_color` | string | No | Filters listings by exterior color (e.g. `White`, `Summit White`, `Gun Metallic`). Accepts multiple values as comma-separated list. | | `facet_sort` | string | No | Sorts facet buckets. Allowed values — `count` (descending count, default) or `index` (alphabetical). | | `facets` | string | No | Field name to return bucket facets for. Accepts multiple fields as a comma-separated list. | | `first_seen_days` | string | No | Filters listings by the number of days since they were first seen in MarketCheck inventory. Specify as `min-max` days. Alternative of `first_seen_range`. | | `first_seen_range` | string | No | Filters listings by the first seen date. Specify as `YYYYMMDD-YYYYMMDD` (e.g., `20220523-20220631`). Alternative of `first_seen_days`. | | `fuel_type` | string | No | Filters listings by fuel type (e.g., `Unleaded`, `Diesel`, `Electric`, `Premium Unleaded`, `Electric / Unleaded`). Accepts multiple values separated by commas. | | `hours_used_range` | string | No | Filters listings by hours used in the case of Heavy Equipment. Specify as `min-max` hours (e.g., `100-500`). | | `interior_color` | string | No | Filters listings by interior color. Accepts multiple values as comma-separated list. | | `last_seen_days` | string | No | Filters listings by the number of days since last seen. Specify as `min-max` days. Alternative of `last_seen_at_range`. | | `last_seen_range` | string | No | Filters listings by last seen date. Specify as `YYYYMMDD-YYYYMMDD` (e.g., `20220523-20220631`). Alternative of `last_seen_at_days`. | | `latitude` | float | No | Latitude component of the search location (decimal degrees). Used for geospatial queries along with `longitude` and `radius` parameters. | | `longitude` | float | No | Longitude component of the search location (decimal degrees). Used for geospatial queries along with `latitude` and `radius` parameters. | | `make` | string | No | Filters listings by vehicle make (e.g., `Toyota`, `Ford`, `Mercedes-Benz`). Accepts multiple values as comma-separated list. | | `miles_range` | string | No | Filters listings by odometer reading. Specify as `min-max` miles (e.g., `1000-50000`). | | `model` | string | No | Filters listings by specific vehicle model (e.g., `Camry`). Accepts multiple values separated by commas. | | `msa_code` | string | No | Filters listings by Metropolitan Statistical Area (MSA) code. | | `msrp_range` | string | No | Filters listings by Manufacturer's Suggested Retail Price (MSRP). Specify as `min-max` USD (e.g., `20000-45000`). | | `price_range` | string | No | Filters listings by advertised price in USD. Specify as `min-max` (e.g., `1000-50000`). | | `radius` | integer | No | Search radius around the specified location in miles. Used with `zip` or `latitude` and `longitude` for geospatial queries. | | `range_facets` | string | No | Comma-separated list of numeric field names for which to return range facets in the response. | | `rows` | integer | No | Number of results to return per request. Default — 10. Maximum — 10. | | `search_text` | string | No | Text substring search within listing titles, descriptions, and other fields. Use `tokenized_search_text` instead for tokenized search. | | `sort_by` | string | No | Field to sort results by. If omitted, defaults to distance when a location filter is used. | | `sort_order` | string | No | Specifies result sort order. Allowed values — `asc` or `desc`. Default — `asc`. | | `source` | string | No | Filters listings by website domain (e.g., `autotrader.com`, `cars.com`). | | `start` | integer | No | Pagination offset (0-based). Default — 0. Maximum page is limited to 10,000/`rows`. | | `state` | string | No | Filters listings by US or Canadian state/province code (e.g., `CA`, `NY`, `ON`). Accepts multiple codes separated by commas. | | `stats` | string | No | Comma-separated list of numeric fields for which to return aggregate statistics (mean, max, min, count). | | `stock_no` | string | No | Filters listings by dealer stock number. | | `sub_category` | string | No | Filters RV listings by their sub-category (e.g., `Travel Trailer`, `Fifth Wheel`). Accepts multiple values as a comma-separated list. | | `transmission` | string | No | Filters listings by transmission type (`Automatic`, `Manual`, etc.). Accepts multiple values separated by commas. | | `trim` | string | No | Filters listings by vehicle trim (e.g., `EX`, `Limited`). Accepts multiple values separated by commas. | | `vin` | string | No | Filters listings by full 17-character Vehicle Identification Number (VIN). | | `year` | string | No | Filters listings by model year (e.g., `2020`). Accepts multiple years separated by commas. | | `zip` | string | No | Filters listings within the specified 5-digit ZIP code. | | `has_price` | boolean | No | Boolean param to filter listings that have a price (true) or no price (false). | | `has_miles` | boolean | No | Boolean param to filter listings that have a miles (true) or no miles (false). | ### Defaults - **inventory_type**: Returns all types (new, used) by default if not specified ### Pagination API response includes `num_found` property indicating the total number of heavy equipment listings matching the search criteria. By default, the API returns the first page of results with 10 listings per page. You can use `start` and `rows` parameters to iterate through search results efficiently. **Parameters:** - `start` - Offset from which listings are returned (starts at 0) - `rows` - Number of listings per page (maximum 10, default 10) Increment `start` proportionally to `rows` value for consistent pagination: - `start=0&rows=10` - fetches listings 1-10 - `start=10&rows=10` - fetches listings 11-20 - `start=20&rows=10` - fetches listings 21-30 **Limits:** - The `rows` parameter accepts a maximum value of 10 (default is 10) - If you specify `rows` greater than 10, the API will automatically use the default value of 10 - If you're on last page of results, the API will return remaining listings, which may be fewer than the requested `rows` - Your subscription package limits the total number of results you can paginate through; exceeding this limit returns an error. > **CAUTION**: > Deep pagination can negatively impact performance and response times. For large-scale data extraction, consider using data feeds instead of paginating through extensive result sets. ### Sorting The Search API allows sorting results by a single numeric or date field at a time. Sorting by multiple fields simultaneously is not supported. **Sort Parameters:** - `sort_by` - Field name to sort by - `sort_order` - Sort direction (`asc` or `desc`) **Default Behavior:** - With location: sorts by distance (nearest first) - Without location: sorts by `last_seen (desc)` and `vin (asc)` **Common Sort Fields** Below are the most commonly used sort fields for heavy equipment searches: | Field Name | sort_by | Data Type | Default Order | Description | |---------------|---------------|---------------|---------------|---------------| | Distance | `dist` | Numeric | asc | Applied by default for geo spatial requests | | Price | `price` | Numeric | asc | Sort listings by price | | Miles | `miles` | Numeric | asc | Sort listings by mileage | | Year | `year` | Numeric | asc | Sort listings by model year | | MSRP | `msrp` | Numeric | asc | Sort listings by MSRP | | Last Seen | `last_seen` | Date | asc | Sort listings by last seen date | | First Seen | `first_seen` | Date | asc | Sort listings by first seen date | | Hours Used | `hours_used` | Numeric | asc | Sort listings by hours used | > **CAUTION**: > Sorting fails silently with incorrect `sort_by` values. Results return with default sorting when invalid sort fields are specified. ## Facets The Search API supports facets for building UI filters and analyzing heavy equipment inventory distribution. Use facets to get unique value counts for categorical fields and range-based counts for numeric fields. ### Field Facets Field facets return unique terms and their counts for categorical data, useful for building search filters and understanding heavy equipment inventory distribution. **Parameters and Syntax** - `facets` — Comma-separated list of field names to facet on. Supports pagination and minimum count:
`facets=field_name|offset|limit|min_count` - Example: `facets=make|0|60|2` returns top 60 makes with at least 2 listings each - `facet_sort` — Controls sort order of facet terms: - `count` (default): Sort by frequency (highest first) - `index`: Sort alphabetically > **IMPORTANT**: > Properly encode facet parameters in your HTTP requests to avoid issues with the pipe (`|`) character, which is used to separate positional parameters. For example, use `%7C` for `|` in URLs. **Example** ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` **Response** - Facets are returned in the `facets` field of the response, structured as key-value pairs - Keys are field names and values are arrays of objects with `item` and `count` properties - `item` is the unique term - `count` is the number of listings for that term. ```json { "facets": { "make": [ { "item": "Caterpillar", "count": 5867 }, { "item": "John Deere", "count": 4809 }, ... ], "city": [ { "item": "Houston", "count": 1000 }, { "item": "Dallas", "count": 800 }, ... ] } } ``` **Available Field Facets** | Field | Description | |-------------|-------------| | body_type | Equipment body type | | category | Equipment category ('Agriculture', etc.) | | city | Listing city location | | cylinders | Engine cylinder count | | dealer_id | MarketCheck dealer ID | | drivetrain | Drivetrain configuration | | engine | Engine specifications | | exterior_color | Exterior color designation | | fuel_type | Fuel system type | | interior_color | Interior color designation | | inventory_type | New or used designation | | make | Equipment manufacturer | | model | Equipment model name | | seller_name | Dealer name (lowercase) | | source | Website domains where listed | | state | Listing state location | | sub_category | Equipment sub-category | | transmission | Transmission type | | trim | Equipment trim level | | year | Equipment model year | | zip | Listing zip code | **Facet Pagination** By default, facets return the top 20 terms for each field. You can control pagination using positional parameters `offset`, `limit`: - `offset` - Starting position for terms (default: 0) - `limit` - Maximum number of terms to return (default: 20, max: 1000) Example: `facets=make|20|20` returns makes 21-40 **Facets Sorting** Facet terms can be sorted by count or alphabetically using the `facet_sort` parameter: - `count` (default) - Sort by frequency (highest first) - `index` - Sort alphabetically Example: `facets=make|0|20&facet_sort=index` returns makes sorted alphabetically > **NOTE**: > Sort order is applied to all facets in the request, not individually. ### Range Facets Range facets provide statistical distribution analysis for numeric fields, creating buckets for data visualization and market insights. **Parameters and Syntax** - `range_facets` — Comma-separated list of field names to facet on, with optional range and interval:
`range_facets=field_name|start|end|interval` - `start` (optional): Lower bound of the range (default varies by field) - `end` (optional): Upper bound of the range (default varies by field) - `interval` (optional): Size of each bucket (default: `(end - start)/20`) - Example: `range_facets=price|500|20000|1000` returns price ranges with 1000 intervals between 500 and 20000. - If `start` is specified but `end` is not, the API adds the default end value for that field to the start value. - Value of `interval` has to be greater than `(end - start)/200`, otherwise the API will return an error. > **IMPORTANT**: > Properly encode facet parameters in your HTTP requests to avoid issues with the pipe (`|`) character, which is used to separate parameters. For example, use `%7C` for `|` in URLs. **Example** ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` **Response** - Range facets are returned in the `range_facets` field of the response, structured as key-value pairs - Keys are field names and values are objects containing: - `counts`: Array of buckets with `lower_bound`, `upper_bound`, and `count` properties - `interval`: Size of each bucket - `start`: Lower bound of the range - `end`: Upper bound of the range - `before`: Count of listings below the start value - `between`: Count of listings within the range - `after`: Count of listings above the end value - If requested field is not allowed for range facets, it will be included in the response but with an error message indicating the field is not supported for range facets. ```json { "range_facets": { "xyz": { "result": "Error", "message": "Field xyz is not allowed in range facets" } } } ``` **Available Range Facets** | Field | Description | Default Range | |---------------|---------------|---------------| | price | Equipment listing price range | 500-10500 | | miles | Equipment mileage range | 0-10000 | | msrp | Manufacturer retail price | 500-10500 | | hours_used | Operating hours range | 100-5100 | > **NOTE**: > All ranges are inclusive of lower_bound and exclusive of upper_bound. The end default value is added to your start value. ## Stats The Search API calculates comprehensive statistics for numeric fields, providing market analysis and competitive intelligence insights for heavy equipment inventory. **Parameters** - `stats` — Comma-separated list of fields to calculate statistics on - Example: `stats=price,miles,hours_used` **Example** ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` **Response** - Statistics are returned in the `stats` field of the response, structured as key-value pairs - Keys are field names and values are objects containing: - `min`: Minimum value - `max`: Maximum value - `count`: Total number of listings with non-null values - `missing`: Number of listings with missing values - `sum`: Total sum of values - `mean`: Average value - `stddev`: Standard deviation - `sum_of_squares`: Sum of squares for variance calculation - `median`: Median value - `percentiles`: Percentile distribution (5th, 25th, 50th, 75th, 90th, 95th, 99th) - If requested field is not allowed for stats, it will be included in the response but with an error message indicating the field is not supported for stats ```json { "stats": { "xyz": { "result": "Error", "message": "Field xyz is not allowed in stats" } } } ``` **Available Stats Fields** Below are the available fields for statistics calculations: | Field | Description | |-------------|-------------| | price | Equipment listing price statistics | | miles | Equipment mileage statistics | | hours_used | Operating hours statistics | ## Spatial Search Search for heavy equipment available near specific locations using geographic coordinates, zip codes, or radius parameters for location-based inventory discovery. **Parameters** - `latitude` and `longitude` - Exact coordinates - `zip` - ZIP code reference point - `radius` - Search radius in **miles** You can combine location parameters with any other search filters for precise geographic targeting. > **NOTE**: > The upper limit of the radius parameter depends on your subscription package. **Example** ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` > **CAUTION**: > Radius values greater than 100 miles may slow API response times. **Response** - Each listing includes a `dist` field with distance from the specified coordinates or ZIP code - Distance is calculated in miles and returned as a numeric value - Results are sorted by distance by default, with nearest listings appearing first ## Response ### Schema The response includes comprehensive heavy equipment listing information with nested objects for media, dealer, and equipment-specific build specifications. ```ts interface HeavyEquipmentSearchResponse { num_found: number; // Total number of listings matching search criteria listings: HeavyEquipmentListing[]; // Array of vehicle listings facets?: Facets; // Field facets (when facets parameter is used) stats?: Stats; // Statistical data (when stats parameter is used) range_facets?: RangeFacets; // Range-based facets (when range_facets parameter is used) } interface HeavyEquipmentListing { id: string; // Unique listing identifier heading: string; // Formatted listing title vin: string; // Vehicle Identification Number price: number; // Current listing price vdp_url: string; // Vehicle detail page URL seller_type: string; // Type of seller (dealer, fsbo, auction) exterior_color: string; // Exterior color description interior_color: string; // Interior color description inventory_type: string; // Inventory classification (new, used) stock_no?: string; // Dealer stock number last_seen_at: number; // Last seen timestamp (Unix Seconds), when the listing was last updated last_seen_at_date: string; // Last seen date (ISO format) scraped_at: number; // First seen timestamp (Unix Seconds), when the listing was first scraped scraped_at_date: string; // First seen date (ISO format) first_seen_at: number; // First seen timestamp (Unix Seconds), when the listing was first seen. Copy of `scraped_at` field first_seen_at_date: string; // First seen date (ISO format) source: string; // Data source website domain media: HeavyEquipmentMedia; // Photos and media content links dealer: HeavyEquipmentDealer; // Dealer information build: HeavyEquipmentBuild; // Vehicle specifications dist?: number; // Distance from search coordinates (if location-based search) } interface HeavyEquipmentMedia { photo_links: string[]; // Array of photo URLs from dealer website } interface HeavyEquipmentDealer { id: number; // Unique dealer identifier website: string; // Dealer website URL name: string; // Dealer business name street: string; // Street address city: string; // City name state: string; // State or province country: string; // Country code latitude: string; // Geographic latitude longitude: string; // Geographic longitude zip: string; // Postal/ZIP code msa_code: string; // Metropolitan Statistical Area code } interface HeavyEquipmentBuild { year: number; // Model year make: string; // Vehicle manufacturer model: string; // Vehicle model engine: string; // Engine description trim: string; // Trim level sub_category: string; // Equipment sub-category length?: string; // Vehicle length category: string; // Equipment category (e.g., Agriculture, Construction) gvwr: string; // Gross Vehicle Weight Rating fuel_type?: string; // Fuel system type (Diesel, LPG, etc.) } interface Facets { [key: string]: { item: string; // Facet term/value count: number; // Number of listings for this term }[]; } interface Stats { [key: string]: { min: number; // Minimum value max: number; // Maximum value count: number; // Number of values missing: number; // Count of missing values sum: number; // Sum of all values mean: number; // Arithmetic mean stddev: number; // Standard deviation sum_of_squares: number; // Sum of squared values median: number; // Median value percentiles: { [key: string]: number; // Percentile values }; }; } interface RangeFacets { [key: string]: { counts: { lower_bound: number; // Range lower bound upper_bound: number; // Range upper bound count: number; // Number of listings in range }[]; interval: number; // Interval size start: number; // Starting value end: number; // Ending value before: number; // Count below start between: number; // Count within range after: number; // Count above end }; } ``` ### Success Response - `200 OK` - Returns JSON object with search results - Always includes `num_found` field indicating total matching listings - `listings` array contains equipment data (empty if no matches) - Optional `facets`, `stats`, and `range_facets` based on request parameters - Missing or null fields are excluded from individual listing objects ### Error Response | Status Code | Description | Common Causes | |---------------|---------------|---------------| | 400 | Bad Request | Invalid parameter values or malformed request | | 401 | Unauthorized | Missing/invalid API key | | 403 | Forbidden | Access denied to resource | | 422 | Unprocessable Entity | Pagination limits exceeded, invalid parameters | | 429 | Too Many Requests | Rate limit exceeded | | 500 | Internal Server Error | Temporary server issues | | 502 | Bad Gateway | Issues with upstream services | | 503 | Service Unavailable | API maintenance or downtime | **Error Response Format** Most error responses follow this structure, except for 502 and 503 errors ```json { "code": , "message": "" } ``` ## Use Cases & Examples ### Filtering by Equipment Specifications Filter listings based on specific equipment attributes like make, model, year, category, and equipment-specific features. This allows users to find equipment that matches their exact preferences. **Example:** Here we're filtering for excavators from 2020 to 2025 from Caterpillar, John Deere. ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` ### Equipment Categories and Types - Use `category` to filter by equipment categories: - `category=Construction` for construction equipment - `category=Agricultural` for Agricultural equipment - `category=Material Handling` for material handling equipment - `category=Crane` for lifting equipment **Example:** Here we're filtering for Agricultural equipment for Caterpillar & John Deere between 2020 and 2025. ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` ### Range Filtering Filter heavy equipment listings within numeric ranges using the following parameters. Range values must be integers in `min-max` format. | Parameter | Type | Default Lower | Default Upper | Description | |---------------|---------------|---------------|---------------|---------------| | price_range | integer | 1000 | 100000 | Filter by price range | | miles_range | integer | 1000 | 100000 | Filter by mileage | | msrp_range | integer | 1000 | 100000 | Filter by MSRP range | | hours_used_range | integer | 100 | 5000 | Filter by operating hours | **Example:** Here we're filtering for equipment in a specific price range. ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` ### Full Text Search Search for specific terms across all heavy equipment listing fields using the `search_text` parameter. **Example:** Here we're searching for equipment with "hydraulic" mentioned anywhere in the listing. ```bash curl --request GET \ --url https://api.marketcheck.com/v2/search/heavy-equipment/active ``` ## See Also - [Heavy Equipment Auto Complete](/docs/api/heavy-equipments/inventory/auto-complete) - [Heavy Equipment Listing Details](/docs/api/heavy-equipments/vehicle-listing/listing) - [Heavy Equipment Dealers Search](/docs/api/heavy-equipments/dealerships/dealers-search)