## 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.

```json
{"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):

```json
{
  "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):

```json
{
  "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](README.md#segment-labels)).

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

```json
{
  "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):

```json
{
  "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](README.md#segment-labels)).

Example (subject: saved title result for Nordic Kayaks NK K1 Kayak):

```json
{
  "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](README.md#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):

```json
{
  "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](README.md#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):

```json
{
  "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"):

```json
{
  "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"):

```json
{
  "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"):

```json
{
  "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"):

```json
{
  "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):

```json
{
  "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):

```json
{
  "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"},
    "..."
  ]
}
```


