Research parameters

Requested with POST /v1/market-research. 14 parameters. A research request names a subject and the parameters. The subject decides which parameters apply; others are refused with 422 unsupported_subject_selection.

An incompatible selection is rejected before billing. The error identifies the unsupported parameters and lists the parameters allowed for the resolved subject. New successful responses include an X-Parameter-Status JSON header with one status per selected parameter: available, no_data, measurement_unavailable, or partial_measurements. These describe the bounded returned observations; zero counts are data. Saved reads and same-key replays preserve this metadata. Older saved results may omit it. Successful empty results still incur the normal parameter charge. Availability does not change the response body or billing.

{"subject": {"type": "title_result", "id": "<X-Result-ID of a completed title request>"}, "parameters": ["market_coverage", "brand_presence"]}

Subjects

Subject type Fields Meaning
product_type value A product type, for example kayak.
brand value A brand name.
category value A shopping category.
dimension dimension, value A season, demographic, occasion or use_case value.
title_result id A completed title result you own; its saved product type becomes the subject.
catalog_group grouping_id, group_id A catalog group you own; its dimension and value become the subject.

Which parameters each resolved subject supports:

Parameter product_type brand category dimension
search_phrases yes -- yes yes
demand_trend yes -- yes yes
geographic_demand yes yes yes yes
market_coverage yes -- -- --
demand_supply_opportunities yes -- yes yes
segment_attribute_distribution yes -- -- --
brand_presence yes yes -- --
seller_concentration yes -- -- --
merchant_type_assortment -- -- yes --
intent_dimension_profile -- -- yes yes
dimension_cooccurrence -- -- yes yes
weekly_market_presence -- -- yes yes
listing_density yes yes -- --
comparable_listings yes yes -- --

Recorded 2026-10-08 by the Prompt Lab on live data, before the 2026-10-09 release; lists cut to two items ("..." marks the cut) and long text shortened. Rows recorded then do not show segment; current responses include it as described.

Parameters

16. search_phrases

Keywords shoppers search for the subject, chosen from stored keyword data.

Returns: {items: [{id, text}], selection: {reviewed, retained}}.

selection says how many stored rows were reviewed and how many were kept.

Example (subject: saved title result for Dog Harness with Leash):

{
  "search_phrases": {
    "items": [{"id": "16328105", "text": "Is this harness suitable for daily walks?"}, {"id": "815905", "text": "dog harness for pulling"}, "..."],
    "selection": {"reviewed": 50, "retained": 35}
  }
}

32. demand_trend

Change in searches between two periods for each keyword.

Returns: {items: [keyword rows], selection: {reviewed, retained}}.

Rows are as in the title parameter of the same name.

Example (subject: saved title result for Dog Harness with Leash):

{
  "demand_trend": {
    "items": [{"id": "813807", "text": "dog carrying harness", "demand_trend": {"change_percent": -18.0556, "baseline_period": "2026-01", "current_period": "2026-02"}, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}}, {"id": "816501", "text": "dog leash nylon", "demand_trend": {"change_percent": -18.5185, "baseline_period": "2026-01", "current_period": "2026-02"}, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}}, "..."],
    "selection": {"reviewed": 50, "retained": 47}
  }
}

34. geographic_demand

Searches for the subject in one country, measured from Google Ads at request time.

Returns: array of {query, keyword, close_variants, market, geographic_target, geographic_name, language, network, provider, observed_at, search_volume, monthly_demand: [{year, month, volume}], meaning}.

Requires market as an uppercase ISO country code (for example GB). English only. Must be requested on its own: other research parameters are not country-scoped and are refused alongside it.

Example: none recorded yet.

35. market_coverage

How many tracked products, merchants and brands are in the product type's market.

Returns: {segment, products, merchants, brands} or null.

Carries segment (see Segment labels).

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

{
  "market_coverage": {
    "products": 1050,
    "merchants": 300,
    "brands": 223
  }
}

36. demand_supply_opportunities

Keywords with real demand compared with how many listings compete for them.

Returns: {items: [{keyword_id, keyword, search_volume, competition_index, score, supply, score_is_upper_bound, basis}], selection}.

score is search volume divided by (1 + competition index). supply is a listing count for the same words, not for the exact product.

Example (subject: saved title result for Dog Harness with Leash):

{
  "demand_supply_opportunities": {
    "items": [{"keyword_id": "815914", "keyword": "dog harness german shepherd", "search_volume": 1300, "competition_index": 100.0, "score": 0.585059, "supply": {"query": "dog harness german shepherd", "hit_cap": 500, "capped": false, "observed_listings": 21, "observed_merchants": 14, "population": "all-query-word Atlas matches from clean stores; lexical supply, not identical products"}, "score_is_upper_bound": false}, {"keyword_id": "1196013", "keyword": "harness for dogs that pull", "search_volume": 12100, "competition_index": 100.0, "score": 0.304066, "supply": {"query": "harness for dogs that pull", "hit_cap": 500, "capped": false, "observed_listings": 393, "observed_merchants": 159, "population": "all-query-word Atlas matches from clean stores; lexical supply, not identical products"}, "score_is_upper_bound": false}, "..."],
    "selection": {"reviewed": 43, "retained": 23}
  }
}

60. segment_attribute_distribution

How the product type's listings split by modifier, colour, material, season, use and occasion.

Returns: array of {segment, dimension, values: [{value, count}]}.

Carries segment (see Segment labels).

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

{
  "segment_attribute_distribution": [
    {"dimension": "modifier", "values": [{"value": "inflatable", "count": 172}, {"value": "lightweight", "count": 15}, "..."]},
    {"dimension": "color", "values": [{"value": "Black", "count": 12}, {"value": "Red", "count": 11}, "..."]},
    "..."
  ]
}

61. brand_presence

Brands in the market and their share of listings.

Returns: array of {segment, name, products, merchants, product_share, observed_at}.

For a product-type subject, each item carries segment (see Segment labels); a brand subject returns that brand's own counts without it. product_share is a share of product count, not of sales.

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

{
  "brand_presence": [
    {"name": "advanced elements", "products": 53, "product_share": 0.050476, "observed_at": "2026-07-16T22:05:27.929000"},
    {"name": "jackson", "products": 33, "product_share": 0.031429, "observed_at": "2026-07-16T22:05:27.929000"},
    "..."
  ]
}

62. seller_concentration

Products per merchant and brand product shares in the observed segment.

Returns: {segment, products_per_merchant, top_3_brand_product_share, top_5_brand_product_share, denominator_products, interpretation} or null.

Carries segment (see Segment labels). Shares are of product count, not sales, and say nothing about how hard the market is to enter.

Despite the legacy parameter name, this does not measure individual sellers' market shares or calculate seller concentration. products_per_merchant is an average; the top-three and top-five shares describe brands.

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

{
  "seller_concentration": {
    "products_per_merchant": 3.5,
    "top_3_brand_product_share": 0.106667,
    "top_5_brand_product_share": 0.149524,
    "denominator_products": 1050
  }
}

63. merchant_type_assortment

A sample of stores selling the category and what kind of store each is.

Returns: {sample: [{id, domain, merchant_type, whole_store_published_products}], sample_size, cap, capped, population}.

Example (subject: category "camping tents"):

{
  "merchant_type_assortment": {
    "sample": [{"id": "62189240479", "domain": "readysetadventuregears.com", "merchant_type": "self_branded", "whole_store_published_products": 77}, {"id": "70726320403", "domain": "www.pandorefitters.com", "merchant_type": null, "whole_store_published_products": 5149}, "..."],
    "sample_size": 50,
    "cap": 50,
    "capped": true
  }
}

64. intent_dimension_profile

The category or shopping dimension's top clusters, questions and keywords.

Returns: {sample_validation, value, cluster_count, top_clusters: [{id, label, count}], top_questions, top_keywords: [{id, text, search_volume}], observed_at, cap, capped}.

Example (subject: category "camping tents"):

{
  "intent_dimension_profile": {
    "sample_validation": "Luna relevance selection; cluster_count describes the unfiltered source population.",
    "value": "camping tents",
    "cluster_count": 1355,
    "top_clusters": [{"id": "132269", "label": "Big Agnes Copper Spur HV UL3 Tent", "count": 121}, {"id": "570870", "label": "Coleman Skydome(TM) 2-Person Camping Tent w/Full-Fly Vestibule - Evergreen", "count": 104}, "..."],
    "top_questions": ["Recommend shelter for group outdoor fun.", "What's good for group outdoor stays?", "..."],
    "top_keywords": [{"id": null, "text": "camping", "search_volume": 1000000}, {"id": null, "text": "tent", "search_volume": 165000}, "..."],
    "observed_at": null,
    "cap": 50,
    "capped": false
  }
}

65. dimension_cooccurrence

Other shopping dimensions that share clusters with the subject.

Returns: array of {dimension, value, shared_clusters}.

Example (subject: category "camping tents"):

{
  "dimension_cooccurrence": [
    {"dimension": "occasions", "value": "camping trips", "shared_clusters": 1151},
    {"dimension": "occasions", "value": "outdoor adventures", "shared_clusters": 301},
    "..."
  ]
}

66. weekly_market_presence

Weekly count of clusters and products for the subject.

Returns: {points: [{week, cluster_count, product_count}], meaning}.

Supply history, not search demand.

Example (subject: category "camping tents"):

{
  "weekly_market_presence": {
    "points": [{"week": "2025-01-01", "cluster_count": 184, "product_count": 6287}, {"week": "2025-01-08", "cluster_count": 184, "product_count": 6287}, "..."]
  }
}

67. listing_density

How many listings and merchants match the subject's words.

Returns: {query, hit_cap, capped, observed_listings, observed_merchants, listings_per_observed_merchant, population}.

A word-match count from clean stores, not a count of identical products.

The hit cap applies before clean-store filtering. capped: true can therefore accompany an observed count below hit_cap; the observed count is a lower bound.

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

{
  "listing_density": {
    "query": "Kayak",
    "hit_cap": 500,
    "capped": true,
    "observed_listings": 498,
    "observed_merchants": 266,
    "population": "all-query-word Atlas matches from clean stores; lexical supply, not identical products"
  }
}

68. comparable_listings

Stored listings from a bounded lexical match to the subject. These are observed examples, not verified substitutes or a current inventory feed. Listing links and current stock are not verified; a source URL can become unavailable after collection.

Returns: array of {id, title, brand, merchant_id, url}.

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

{
  "comparable_listings": [
    {"id": "90669347", "title": "Kayak King(R) Spin", "brand": "Emmrod", "merchant_id": "1539619", "url": "https://www.compactfishingpole.com/products/kayak-king-spin"},
    {"id": "152446345", "title": "Escape Hard Shell Kayak", "brand": "Conquest", "merchant_id": "2595141", "url": "https://kayaks.myshopify.com/products/escape-hard-shell-kayak"},
    "..."
  ]
}

Plain-text version: /docs/research-parameters.md