Shopping Aggregates

GET /api/v1/shopping-aggregates returns the Shopping feature's window-level rollups: one row per surface, dimension, and dimension key. The four dimensions carry different measures inside the metrics object, which is why the endpoint exposes them as one resource with a dimension filter rather than four fixed shapes.

Filters

Standard parameters (limit, offset, format=csv) work as described in Pagination, filtering, and errors.

Key fields

• measurement_window_id: joinable to measurement windows
• surface: the shopping surface the row covers; all spans every covered surface, and rates never mix surfaces without that label
• dimension and dimension_key: what the row measures, either a catalog product_id, a merchant name, a prompt_id, or a cited source domain
• metrics: the measures for that dimension:
  • product: appearances, answers_with_product, total_answers, visibility_rate, avg_position, win_rate (share of appearances at position 1)
  • merchant: appearances, share_of_voice, buybox_rate, avg_price_ratio (observed price vs the cross-merchant median)
  • prompt: answers, answers_with_shopping, trigger_rate (share of the prompt's answers that produced shopping results)
  • source: citations
• computed_at: when the rollup was written

Rows are ordered by measurement_window_id descending with surface, dimension, and key as tiebreaks, so offset pagination is stable. Deltas between windows are computed by comparing rows across measurement_window_id values.

Example

curl -H "Authorization: Bearer $AEO_API_KEY" \
  "https://app.citlyze.com/api/v1/shopping-aggregates?dimension=product&surface=all"

Use this resource to export SKU visibility, merchant share of voice, and shopping trigger rates into BI tools, and to trend them window over window.