Shopping Performance

Report how one store's products perform in Google's free listings and how they stand against the market, ending with the offers and prices to act on. The user's request may contain a property, a date range, a country (ISO 3166-1 alpha-2), a Google product taxonomy category id, a brand or offer id, or a focus hint such as "pricing" or "competitors"; honor it by going deeper there, but still run the core steps.

Workflow

1. Resolve the property and the window. If the user's request or the conversation names a property, use it. Site URLs use GSC formats: sc-domain:example.com or https://www.example.com/. Otherwise call list_sites and pick the obvious match. If several plausible properties exist, ask the user which one before continuing. Then fix the window:

   • Use the last 28 days compared with the previous period unless the user specifies dates; omitting both startDate and endDate gives the default window.
   • For the Search Console data in step 2, GSC data lags about 2 to 3 days: never treat the most recent 2 days as complete, and if a dip appears at the very edge of the range, say it is likely reporting lag, not a real drop.
   • Merchant Center (steps 3 to 7) reports on its own calendar and carries no partialDays flag, so say that the newest day may still fill in rather than reading it as a drop, and the best-seller reports lag up to two weeks.
   • Neither performance tool takes a comparison range: for a period-over-period view call it a second time with explicit prior-period dates and derive the deltas yourself, saying so.

2. Merchant listings in web Search. Call get_merchant_listings_performance with siteUrl and the default appearance: "MERCHANT_LISTINGS" unless the user asks for another code (limit default 25, max 1000, top pages by clicks; includeAppearances defaults to true). Read:

   • hasAppearance and appearances first: that breakdown is the only way to learn which search appearance codes the property has (PRODUCT_SNIPPETS and ORGANIC_SHOPPING are common) and how big each one is.
   • totals, the daily timeline and the top pages. This is always the live Search Console API: it counts enriched product results in web Search only, the appearance can only be filtered on and never grouped with another dimension, the window is capped at 16 months, and the call costs 3 rate-limit units. ctr values are already percentages on a 0-100 scale. Never multiply them by 100. position: lower is better. A change toward a lower number is an improvement; never color it as a decline.

3. Organic shopping performance. Call get_organic_shopping_performance with siteUrl, groupBy: "offer" (the default; the enum also allows "brand", "category" for Google taxonomy level 1 and "productType" for the merchant's own taxonomy), limit (default 25, max 200, ordered by organic clicks) and includeNonProduct (default true). Read totals and the daily timeline (clicks, impressions, ctr, conversions, conversionValue in currencyCode), the rows[] (key, title and the same metrics) and nonProductTimeline for clicks to category and home pages. The ctr here is on the same 0-100 scale as step 2, so never multiply it by 100. Conversions need a Merchant Center conversion source; conversionNote says when they are absent. Call it again with groupBy: "brand" or "category" when the user asks about the mix. This covers every free surface (Shopping tab, Search, Images, Lens, YouTube, Maps), so it never reconciles with step 2; compare their trends, not their totals. Organic excludes YouTube affiliate traffic from 1 July 2026 onward, so a step down at that date is a definition change, not a loss. Underperformers are offers with many impressions and a ctr well below the table's typical value, or many clicks and zero conversions where conversions are reported.