{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ecommercedataapi-com/json-schema/ecommercedataapi-com-amazon-products-research-request-schema.json",
  "title": "AmazonProductsResearchRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ecommercedataapi-com-openapi.json#/components/schemas/AmazonProductsResearchRequest",
  "type": "object",
  "properties": {
    "availableMonth": {
      "type": "integer",
      "format": "int32",
      "description": "Limit products by listing age: 1, 3, 6, 12, or 24 months. Omit the field for no listing-age restriction."
    },
    "badgeAC": {
      "type": "string",
      "description": "Set to Y to require an Amazon's Choice badge."
    },
    "badgeBS": {
      "type": "string",
      "description": "Set to Y to require a Best Seller badge."
    },
    "badgeNR": {
      "type": "string",
      "description": "Set to Y to require a New Release badge."
    },
    "dimensionType": {
      "type": "string",
      "description": "Comma-separated product size-tier codes. Codes vary by marketplace; for example US values include ST, LS, SO, MO, LO, SP, O, ELO, EL5O, EL7O, and EL15O. Available values (Table 1.4): United States: ST, SS, LS, SO, MO, LO, LB, SP, O, ELO, EL5O, EL7O, EL15O; Japan: SM, ST, OV, SS, O; Canada: EN, ST, SO, MO, LO, SP, O; Europe (UK/DE/FR/IT/ES): SL, NL, LL, ELL, SM, SD, SB, NB, LB, SPO, O"
    },
    "excludeBrands": {
      "type": "string",
      "description": "Exclude products from the specified brand filter."
    },
    "excludeKeywords": {
      "type": "string",
      "description": "Keywords to exclude from the product results."
    },
    "excludeSellers": {
      "type": "string",
      "description": "Exclude products sold by this seller. Use the store name as shown on Amazon, such as Amazon.com; seller IDs such as A1MCYUGJD2ILFU exclude nothing."
    },
    "filterSub": {
      "type": "string",
      "description": "Set to Y to apply the subcategory-rank filters. It only takes effect when a category is specified."
    },
    "fulfillment": {
      "type": "string",
      "description": "Fulfillment types separated by commas. Supported values are AMZ, FBA, and FBM."
    },
    "includeBrands": {
      "type": "string",
      "description": "Only include products from the specified brand filter."
    },
    "includeSellers": {
      "type": "string",
      "description": "Only include products sold by this seller. Use the store name as shown on Amazon, such as Amazon.com; seller IDs such as A1MCYUGJD2ILFU match nothing."
    },
    "keyword": {
      "type": "string",
      "description": "Product keyword used to filter listing titles and related text."
    },
    "marketplace": {
      "type": "string",
      "enum": [
        "US",
        "UK",
        "DE",
        "FR",
        "IT",
        "ES",
        "MX",
        "CA",
        "AU",
        "JP",
        "IN",
        "AE",
        "BR"
      ],
      "description": "Amazon marketplace code. Supported values: US, UK, DE, FR, IT, ES, MX, CA, AU, JP, IN, AE, and BR."
    },
    "matchType": {
      "type": "integer",
      "format": "int32",
      "description": "Keyword match mode: 1 for phrase match, 2 for broad match, or 3 for exact match. Defaults to 2."
    },
    "maxAmzUnit": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum recent sales estimate for the current ASIN. This filter is available for latest-30-day queries."
    },
    "maxBsr": {
      "type": "integer",
      "format": "int32",
      "description": "Worst boundary for the top-level Best Sellers Rank. Smaller BSR values indicate a better rank."
    },
    "maxBsrCr": {
      "type": "number",
      "format": "float",
      "description": "Maximum BSR change rate as a percentage value."
    },
    "maxBsrCv": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum numeric BSR change for the selected month."
    },
    "maxFba": {
      "type": "number",
      "format": "float",
      "description": "Maximum estimated FBA fee in the marketplace currency."
    },
    "maxLqs": {
      "type": "number",
      "format": "float",
      "description": "Maximum listing quality score."
    },
    "maxPrice": {
      "type": "number",
      "format": "float",
      "description": "Maximum product price in the marketplace currency."
    },
    "maxProfit": {
      "type": "number",
      "format": "float",
      "description": "Maximum estimated gross margin percentage."
    },
    "maxRating": {
      "type": "number",
      "format": "float",
      "description": "Maximum average star rating."
    },
    "maxRatings": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum total rating count."
    },
    "maxRatingsCv": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum number of newly added ratings in the selected month."
    },
    "maxRevenue": {
      "type": "number",
      "format": "float",
      "description": "Maximum estimated monthly revenue in the marketplace currency."
    },
    "maxRevenueCr": {
      "type": "number",
      "format": "float",
      "description": "Maximum monthly revenue growth rate as a percentage value."
    },
    "maxSellers": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum number of sellers on the listing."
    },
    "maxSubBsrRank": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum subcategory rank. Requires filterSub=Y."
    },
    "maxUnits": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum estimated monthly sales for the parent listing."
    },
    "maxUnitsCr": {
      "type": "number",
      "format": "float",
      "description": "Maximum monthly sales growth rate as a percentage value."
    },
    "maxVariations": {
      "type": "integer",
      "format": "int32",
      "description": "Maximum variation count."
    },
    "maxWeights": {
      "type": "number",
      "format": "float",
      "description": "Maximum product weight expressed in weightUnit."
    },
    "minAmzUnit": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum recent sales estimate for the current ASIN. This filter is available for latest-30-day queries."
    },
    "minBsr": {
      "type": "integer",
      "format": "int32",
      "description": "Best boundary for the top-level Best Sellers Rank. Smaller BSR values indicate a better rank."
    },
    "minBsrCr": {
      "type": "number",
      "format": "float",
      "description": "Minimum BSR change rate as a percentage value."
    },
    "minBsrCv": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum numeric BSR change for the selected month."
    },
    "minFba": {
      "type": "number",
      "format": "float",
      "description": "Minimum estimated FBA fee in the marketplace currency."
    },
    "minLqs": {
      "type": "number",
      "format": "float",
      "description": "Minimum listing quality score."
    },
    "minPrice": {
      "type": "number",
      "format": "float",
      "description": "Minimum product price in the marketplace currency."
    },
    "minProfit": {
      "type": "number",
      "format": "float",
      "description": "Minimum estimated gross margin percentage."
    },
    "minRating": {
      "type": "number",
      "format": "float",
      "description": "Minimum average star rating."
    },
    "minRatings": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum total rating count."
    },
    "minRatingsCv": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum number of newly added ratings in the selected month."
    },
    "minRevenue": {
      "type": "number",
      "format": "float",
      "description": "Minimum estimated monthly revenue in the marketplace currency."
    },
    "minRevenueCr": {
      "type": "number",
      "format": "float",
      "description": "Minimum monthly revenue growth rate as a percentage value."
    },
    "minSellers": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum number of sellers on the listing."
    },
    "minSubBsrRank": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum subcategory rank. Requires filterSub=Y."
    },
    "minUnits": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum estimated monthly sales for the parent listing."
    },
    "minUnitsCr": {
      "type": "number",
      "format": "float",
      "description": "Minimum monthly sales growth rate as a percentage value."
    },
    "minVariations": {
      "type": "integer",
      "format": "int32",
      "description": "Minimum variation count."
    },
    "minWeights": {
      "type": "number",
      "format": "float",
      "description": "Minimum product weight expressed in weightUnit."
    },
    "month": {
      "type": "string",
      "description": "Data month. Use \"nearly\" for the latest 30 days or yyyyMM for a specific month within the previous 24 months. Available values (Table 1.1): nearly, yyyyMM"
    },
    "nodeIdPath": {
      "type": "string",
      "description": "Single Amazon category node path. Use the category endpoint to obtain a node path."
    },
    "nodeIdPathEqual": {
      "type": "boolean",
      "description": "When true, match only the exact category path. When false, include its descendant categories. Defaults to false."
    },
    "nodeIdPaths": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "Amazon category node paths. Use the category endpoint to obtain node paths."
      },
      "description": "Amazon category node paths. Use the category endpoint to obtain node paths."
    },
    "order": {
      "type": "object",
      "properties": {
        "desc": {
          "type": "boolean",
          "description": "Use true for descending order or false for ascending order. Defaults to true."
        },
        "field": {
          "type": "string",
          "description": "Sort field: total_units, total_amount, bsr_rank, price, rating, reviews, profit, reviews_rate, available_date, or questions. Defaults to total_units. Available values (Table 1.6): total_units, total_amount, bsr_rank, price, rating, reviews, profit, reviews_rate, available_date, questions, total_units_growth, total_amount_growth, reviews_increasement, bsr_rank_cv, bsr_rank_cr, amz_unit"
        }
      },
      "additionalProperties": false,
      "description": "Sort definition."
    },
    "page": {
      "type": "integer",
      "format": "int32",
      "minimum": 1,
      "description": "Page number starting at 1. Defaults to 1. A query can return at most 2,000 records; narrow the filters to retrieve additional segments."
    },
    "returnFields": {
      "type": "string",
      "description": "Optional response-field selection string. Omit it to receive the standard response payload."
    },
    "sellerNation": {
      "type": "string",
      "description": "Seller country or region codes. Multiple values can be separated by commas; common values include CN, HK, US, JP, DE, and FR. Available values (Table 1.5): CN, HK, US, JP, DE, FR"
    },
    "size": {
      "type": "integer",
      "format": "int32",
      "minimum": 1,
      "description": "Results per page. Defaults to 50 and supports up to 100."
    },
    "variation": {
      "type": "string",
      "description": "Variation handling: N includes variation ASINs; Y excludes variation ASINs."
    },
    "weightUnit": {
      "type": "string",
      "enum": [
        "g",
        "kg",
        "oz",
        "lb"
      ],
      "description": "Unit used by minWeights and maxWeights: g, kg, oz, or lb. Defaults to g."
    }
  },
  "required": [
    "marketplace"
  ],
  "additionalProperties": false
}