Inventory Search

The Inventory Search API enables searching and filtering recreational vehicle listings from UK dealers and marketplaces. This endpoint provides comprehensive search capabilities across motorhomes, caravans, campervans, and travel trailers with detailed filtering options for type, price, location, and vehicle specifications.

Overview

• Access active dealer RV inventory across UK markets with thousands of listings
• Data updates published regularly for current market conditions
• Comprehensive filtering with 50+ parameters specific to recreational vehicles

Units & Conventions:

Base Path

GET https://api.marketcheck.com/v2/search/rv/uk/active

The following example demonstrates a basic search for recreational vehicles:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/rv/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 2,
    make: 'Bailey',
    year: 2023,
    start: 0,
    facets: 'category',
    stats: 'price'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Explore the complete parameter options and response structure in the Request section below.

Request

The RV Inventory Search API provides flexible search and filtering capabilities for recreational vehicle listings. Search results include listing IDs that can be used with the Vehicle Listing API to retrieve detailed information.

Parameters

Available parameters for RV inventory search:

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 RV 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 50, default 10)

Increment start proportionally to rows value for consistent pagination:

• start=0&rows=50 - fetches listings 1-50
• start=50&rows=50 - fetches listings 51-100
• start=100&rows=50 - fetches listings 101-150

Limits:

• The rows parameter accepts a maximum value of 50 (default is 10)
  • If you specify rows greater than 50, 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.

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)

Common Sort Fields

Below are the most commonly used sort fields for RV searches:

Facets

The Search API supports facets for building UI filters and analyzing RV 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 RV 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

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/rv/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 0,
    make: 'Bailey',
    year: 2024,
    facets: 'model|0|100,city|0|100'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

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.

{
"facets": {
    "make": [
    { "item": "Bailey", "count": 984 },
    { "item": "Swift", "count": 870 },
    ...
    ],
    "city": [
    { "item": "Somerset", "count": 1147 },
    { "item": "Doncaster", "count": 364 },
    ...
    ]
}
}

Available Field Facets

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

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.

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/rv/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 0,
    make: 'Bailey',
    year: 2024,
    range_facets: 'price|500|100000|10000,miles|5000|50000|5000'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

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.

  {
    "range_facets": {
      "xyz": {
        "result": "Error",
        "message": "Field xyz is not allowed in range facets"
      }
    }
  }
  

Available Range Facets

Stats

The Search API calculates comprehensive statistics for numeric fields, providing market analysis and competitive intelligence insights for RV inventory.

Parameters

• stats — Comma-separated list of fields to calculate statistics on
  • Example: stats=price,miles

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/rv/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 0,
    year: '2024',
    make: 'Bailey',
    stats: 'price,miles'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

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

  {
    "stats": {
      "xyz": {
        "result": "Error",
        "message": "Field xyz is not allowed in stats"
      }
    }
  }
  

Available Stats Fields

Below are the available fields for statistics calculations:

Spatial Search

Search for RVs available near specific locations using geographic coordinates, postal codes, or radius parameters for location-based inventory discovery.

Parameters

• latitude and longitude - Exact coordinates
• postal_code - Postal code reference point
• radius - Search radius in miles

You can combine location parameters with any other search filters for precise geographic targeting.

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/rv/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 2,
    make: 'Bailey',
    year: 2023,
    start: 0,
    postal_code: 'DN10 6DG',
    radius: 100
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Use Cases & Examples

Search Motorhomes by Location

Find motorhomes available from dealers in specific regions, useful for customers looking for RVs within reasonable travel distance.

Example:

Here we're searching for motorhomes in the London area:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/rv/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 2,
    make: 'Bailey',
    year: 2023,
    start: 0,
    facets: 'category',
    stats: 'price'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Response

The API returns search results with basic RV information and listing details. Each result includes a unique listing ID that can be used with the Vehicle Listing API for detailed information.

Response Schema

Successful responses return a JSON object containing:

interface RVSearchResponse {
  num_found: number; // Total number of listings matching search criteria
  listings: RVListing[]; // 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 RVListing {
  id: string; // Unique listing identifier
  heading: string; // Formatted listing title
  price: number; // Current listing price
  miles: number; // Vehicle mileage
  vdp_url: string; // Vehicle detail page URL
  seller_type: string; // Type of seller (dealer, fsbo, auction)
  inventory_type: string; // Inventory classification (new, used)
  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
  miles_indicator: string; // Mileage unit indicator
  currency_indicator: string; // Currency unit indicator
  motorhome_build: string; // Motorhome build specifications
  origin: string; // Vehicle origin information
  media: RVMedia; // Photos and media content links
  dealer: RVDealer; // Dealer information
  build: RVBuild; // Vehicle specifications
  dist?: number; // Distance from search coordinates (if location-based search)
}

interface RVMedia {
  photo_links: string[]; // Array of photo URLs from dealer website
  floorplan_image_link?: string; // Floorplan image URL
}

interface RVDealer {
  id: number; // Unique dealer identifier
  website: string; // Dealer website URL
  name: string; // Dealer business name
  street: string; // Street address
  city: string; // City name
  county: string; // County name
  country: string; // Country code
  latitude: string; // Geographic latitude
  longitude: string; // Geographic longitude
  zip: string; // Postal/ZIP code
  phone: string; // Contact phone number
}

interface RVBuild {
  year: number; // Model year
  make: string; // Vehicle manufacturer
  model: string; // Vehicle model
  transmission: string; // Transmission type
  fuel_type: string; // Fuel type (gasoline, electric, hybrid, etc.)
  engine: string; // Engine description
  drive_type: string; // Drive type configuration
  chassis: string; // Chassis specifications
  berths: string; // Sleeping capacity
  exterior_length?: string; // Vehicle length
  mtplm?: string; // Maximum Technically Permissible Laden Mass
  steering: string; // Steering configuration
  category: string; // Vehicle category
}

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 vehicle 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

Error Response Format

Most error responses follow this structure, except for 502 and 503 errors

{
  "code": <HTTP status code>,
  "message": "<Error message describing the issue>"
}