## Title parameters

Requested with `POST /v1/title-matches`. 38 parameters. Shared rules, labels and request fields are in the [parameter reference](README.md).

```json
{"title": "Nordic Kayaks NK K1 Kayak", "parameters": ["product_type", "search_volume"], "keywords": ["sit in kayak"]}
```

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 `metrics_status`, `retrieval` or `graph_coverage`, and their `context` fields were empty because the stored rows had not recorded them; current responses include these fields as described.

### Product facts and shopping context

#### 1. title

The submitted title, returned unchanged.

Returns: string.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "title": "Nordic Kayaks NK K1 Kayak"
}
```

#### 2. product_type

What the product is, as a short noun phrase.

Returns: string or null.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "product_type": "Kayak"
}
```

#### 3. brand

The brand named in the title.

Returns: string or null.

null when no brand is identified.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "brand": "Nordic Kayaks"
}
```

#### 4. attributes

Specifications the title states, as name and value pairs.

Returns: array of `{name, value}`.

Only what the title says, plus any description or attributes you send; nothing is inferred. Empty when none of them states a specification.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "attributes": [
    {"name": "Model", "value": "NK K1"}
  ]
}
```

#### 5. categories

Shopping categories the product belongs in.

Returns: array of strings.

Shopping associations need not appear in the title.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "categories": [
    "Kayaks",
    "Water sports gear",
    "..."
  ]
}
```

#### 6. use_cases

What shoppers use the product for.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "use_cases": [
    "Recreational paddling",
    "Lake exploration",
    "..."
  ]
}
```

#### 7. occasions

Events and occasions the product suits.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "occasions": [
    "lake outings",
    "river paddling",
    "..."
  ]
}
```

#### 8. audiences

Who the product is for.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "audiences": [
    "kayakers",
    "paddlers",
    "..."
  ]
}
```

#### 9. seasons

Seasons the product is relevant to.

Returns: array of strings.

Can be empty for products with no season.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "seasons": [
    "Spring",
    "Summer",
    "..."
  ]
}
```

#### 10. where

Places the product is used.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "where": [
    "Lakes",
    "Rivers",
    "..."
  ]
}
```

#### 11. why

Reasons shoppers want the product.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "why": [
    "outdoor recreation",
    "water exploration",
    "..."
  ]
}
```

#### 12. how

How the product is used.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "how": [
    "paddle across lakes and rivers",
    "use for recreational outings on the water"
  ]
}
```

### Keywords and questions

#### 13. intent_phrases

Phrases describing what a shopper is trying to do, written for this product.

Returns: array of `{text, basis}`.

`basis` is always `suggested`: these are written, not measured searches. They carry no keyword ID or figures.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "intent_phrases": [
    {"text": "Find a kayak for recreational paddling", "basis": "suggested"},
    {"text": "Compare kayaks for lake and river paddling", "basis": "suggested"},
    "..."
  ]
}
```

#### 14. long_tail_keywords

Longer, more specific keywords for the product, chosen from stored keyword data.

Returns: array of `{id, text}` plus `retrieval` and `graph_coverage` when known.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "long_tail_keywords": [
    {"id": "2137192", "text": "river kayak"},
    {"id": "8963537", "text": "Which kayak suits calm waters?"},
    "..."
  ]
}
```

#### 15. buyer_questions

Real shopper questions for the product, chosen from stored question data.

Returns: array of `{id, text, parent_cluster_id, parent_search_volume, basis}`.

`parent_search_volume` is the volume of the parent keyword or cluster the question belongs to, not of the question itself. Questions can read like buying phrases and can lack a question mark.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "buyer_questions": [
    {"id": "21026", "text": "kayaks for sale", "parent_cluster_id": "18586424", "parent_search_volume": 0, "basis": "retrieved"},
    {"id": "323581", "text": "kayak for beginners", "parent_cluster_id": "18586424", "parent_search_volume": 12516, "basis": "retrieved"},
    "..."
  ]
}
```

#### 16. search_phrases

Keywords shoppers search for the product, chosen from stored keyword data.

Returns: array of `{id, text}` plus `retrieval` and `graph_coverage` when known.

Keywords you send in `keywords` can add rows here (see [Your own keywords](README.md#your-own-keywords)).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "search_phrases": [
    {"id": "1384084", "text": "kayak sale"},
    {"id": "1384373", "text": "kayaks for sale"},
    "..."
  ]
}
```

### Merchandising and taxonomy

#### 17. synonyms

Other names shoppers use for the product.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "synonyms": [
    "kayak boat"
  ]
}
```

#### 18. cluster_ids

IDs of product clusters retrieved as context for the title.

Returns: array of strings.

Clusters are a related-product neighbourhood, not verified exact matches. They may
include other brands, sizes or variants; membership does not establish compatibility.
Look one up with `GET /v1/clusters/{cluster_id}`.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "cluster_ids": [
    "4312254",
    "3384791",
    "..."
  ]
}
```

#### 19. category_paths

Suggested paths in the Google product taxonomy.

Returns: array of `{system, version, basis, ids, labels}`.

`ids` and `labels` run from the top level down. `basis` is `suggested`; the IDs and labels themselves are real taxonomy entries.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "category_paths": [
    {"system": "google_product_category", "version": "2021-09-21", "basis": "suggested", "ids": ["988", "1011", "..."], "labels": ["Sporting Goods", "Outdoor Recreation", "..."]}
  ]
}
```

#### 20. taxonomy_mappings

The suggested Google product category for the product.

Returns: array of `{basis, system, category_id, label, version, market}`.

`label` is the full path text. `basis` is `suggested`.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "taxonomy_mappings": [
    {"basis": "suggested", "system": "google_product_category", "category_id": "1127", "label": "Sporting Goods > Outdoor Recreation > Boating & Water Sports > Boating & Rafting > Kayaks", "version": "2021-09-21"}
  ]
}
```

#### 21. collection_suggestions

Store collections the product could be placed in, with the rule for each.

Returns: array of `{name, criteria, basis}`.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "collection_suggestions": [
    {"name": "Nordic Kayaks", "criteria": ["Brand: Nordic Kayaks"], "basis": "suggested"}
  ]
}
```

#### 22. facets

Filter facets taken from the title.

Returns: array of `{name, values}`.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "facets": [
    {"name": "model", "values": ["NK K1"]}
  ]
}
```

#### 23. related_product_types

Products bought alongside this one.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "related_product_types": [
    "Kayak paddles",
    "Personal flotation devices",
    "..."
  ]
}
```

#### 24. alternative_product_types

Products a shopper might choose instead.

Returns: array of strings.

Example (subject: Signature Insulated Water Bottle):

```json
{
  "alternative_product_types": [
    "Insulated travel mug",
    "Insulated tumbler"
  ]
}
```

#### 25. compatibility

An explicitly named host product, interface or system from the title.

Returns: array of strings.

Only from the title, as a whole word, and never when preceded by not, no, non, without or incompatible. Often empty.

A broad host such as Vacuum Cleaner does not establish fit with a particular model.
An interface such as USB does not verify every device or power requirement. Check
the manufacturer's fit and operating requirements before treating it as compatible.

Example (subject: Dog Harness with Leash):

```json
{
  "compatibility": [
    "Dog"
  ]
}
```

#### 26. variant_dimensions

Ways the product could come in different versions, such as size or colour.

Returns: array of `{name, values, basis}`.

`basis` `suggested` means a likely dimension, not observed variants of this product; `values` can be empty.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "variant_dimensions": [
    {"name": "Color", "values": [], "basis": "suggested"},
    {"name": "Kayak length", "values": [], "basis": "suggested"},
    "..."
  ]
}
```

#### 27. missing_attributes

Specifications a shopper would want that the title does not state.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "missing_attributes": [
    "Length",
    "Width",
    "..."
  ]
}
```

#### 28. localized_terms

Suggested translations or search wording for the product in a given locale.

Returns: array of `{text, basis, locale}`.

Requires `locale` in the request (for example `en-GB`). Sending `locale` without this parameter is refused.

These are suggestions, not measured local demand. The locale applies to this field;
it does not translate stored search phrases or change their measurement market.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "localized_terms": [
    {"text": "kayak", "basis": "suggested", "locale": "en"},
    {"text": "K1 kayak", "basis": "suggested", "locale": "en"},
    "..."
  ]
}
```

### Keyword measurements

These seven parameters return one row per keyword with its figures. You can add your own keywords to them with `keywords`; see [Your own keywords](README.md#your-own-keywords).

#### 29. cpc

Cost per click for each keyword.

Returns: array of keyword rows; value: number or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "cpc": [
    {"id": "1384084", "text": "kayak sale", "cpc": 0.36, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "cpc": 0.535, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

#### 30. search_volume

Average monthly searches for each keyword.

Returns: array of keyword rows; value: integer or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "search_volume": [
    {"id": "1384084", "text": "kayak sale", "search_volume": 2900, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "search_volume": 40500, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

#### 31. paid_search_competition

Paid-search competition level for each keyword.

Returns: array of keyword rows; value: `LOW`, `MEDIUM`, `HIGH` or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "paid_search_competition": [
    {"id": "1384084", "text": "kayak sale", "paid_search_competition": "HIGH", "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "paid_search_competition": "HIGH", "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

#### 32. demand_trend

Change in searches between two periods for each keyword.

Returns: array of keyword rows; value: `{change_percent, baseline_period, current_period}` or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "demand_trend": [
    {"id": "1384084", "text": "kayak sale", "demand_trend": {"change_percent": 30.0, "baseline_period": "2026-01", "current_period": "2026-02"}, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "demand_trend": null, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

#### 33. monthly_demand

Monthly searches for each keyword.

Returns: array of keyword rows; value: `{points: [{year, month, volume}], peak_months}` or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "monthly_demand": [
    {"id": "1384084", "text": "kayak sale", "monthly_demand": {"points": [{"year": 2025, "month": 3, "volume": 2900}, {"year": 2025, "month": 4, "volume": 2900}, "..."], "peak_months": [7]}, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "monthly_demand": null, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

### Keyword analysis

#### 41. keyword_intent_stages

Where each keyword sits in the buying journey.

Returns: array of `{id, text, keyword_intent_stages: {stage, reason}}`.

`stage` is `informational`, `commercial` or `transactional`.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "keyword_intent_stages": [
    {"id": "1384084", "text": "kayak sale", "keyword_intent_stages": {"stage": "transactional", "reason": "Seeks kayaks available to buy."}},
    {"id": "1384373", "text": "kayaks for sale", "keyword_intent_stages": {"stage": "transactional", "reason": "Seeks kayaks available for purchase."}},
    "..."
  ]
}
```

#### 42. keyword_bid_range

Low and high top-of-page bid for each keyword.

Returns: array of keyword rows; value: `{low, high}` or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "keyword_bid_range": [
    {"id": "1384084", "text": "kayak sale", "keyword_bid_range": {"low": 0.12, "high": 0.61}, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "keyword_bid_range": {"low": 0.18, "high": 0.89}, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

#### 43. competition_index

Paid-search competition as a number from 0 to 100 for each keyword.

Returns: array of keyword rows; value: number or null.

Each row: `id` (keyword ID), `text`, the value named after the parameter, `context` (market, language, currency, measurement_period, observed_at, provider), `metrics_status`, and when known `retrieval` and `graph_coverage`. See [Keyword rows](README.md#keyword-rows).

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "competition_index": [
    {"id": "1384084", "text": "kayak sale", "competition_index": 100.0, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    {"id": "1384373", "text": "kayaks for sale", "competition_index": 100.0, "context": {"market": null, "language": null, "currency": null, "measurement_period": null, "observed_at": null, "provider": null}},
    "..."
  ]
}
```

#### 44. keyword_graph_coverage

Whether each keyword is linked to a product cluster.

Returns: array of `{id, text, keyword_graph_coverage}`.

Linkage is read from the stored keyword, never from how it was found.

This list covers selected discovery keywords. Additional measurement-only fallback
rows carry their own `graph_coverage` metadata inside measurement answers, but are
not added to this list. An empty list is not a claim that every measured query lacks
a graph link.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "keyword_graph_coverage": [
    {"id": "1384373", "text": "kayaks for sale", "keyword_graph_coverage": true},
    {"id": "2097452", "text": "recreational kayak", "keyword_graph_coverage": true},
    "..."
  ]
}
```

#### 45. keyword_product_matches

Which keywords match your product, by shared words.

Returns: array of `{keyword_id, product_ids, basis}`.

Requires `client_product_id` in the request; `product_ids` holds that ID. `basis` is `suggested_token_overlap`.

Example (subject: Nordic Kayaks NK K1 Kayak):

```json
{
  "keyword_product_matches": [
    {"keyword_id": "1384084", "product_ids": ["title-kayaks-B"], "basis": "suggested_token_overlap"},
    {"keyword_id": "1384373", "product_ids": ["title-kayaks-B"], "basis": "suggested_token_overlap"},
    "..."
  ]
}
```


