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