Title parameters

Requested with POST /v1/title-matches. 38 parameters. Shared rules, labels and request fields are in the parameter reference.

{"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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "occasions": [
    "lake outings",
    "river paddling",
    "..."
  ]
}

8. audiences

Who the product is for.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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):

{
  "seasons": [
    "Spring",
    "Summer",
    "..."
  ]
}

10. where

Places the product is used.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "where": [
    "Lakes",
    "Rivers",
    "..."
  ]
}

11. why

Reasons shoppers want the product.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "why": [
    "outdoor recreation",
    "water exploration",
    "..."
  ]
}

12. how

How the product is used.

Returns: array of strings.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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):

{
  "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):

{
  "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):

{
  "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).

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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.

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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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):

{
  "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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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.

Example (subject: Nordic Kayaks NK K1 Kayak):

{
  "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):

{
  "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):

{
  "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"},
    "..."
  ]
}

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