با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
Merchant API گزارش‌های عملکرد را ارائه می‌کند، به عنوان مثال product_performance_view . این صفحه ساختار گزارش های عملکرد را توضیح می دهد.
معیارها
می‌توانید معیارهایی (به عنوان مثال، clicks و impressions ) را که می‌خواهید برگردانده شوند، جستجو کنید. برای پرس و جو از سرویس گزارش ها برای داده های عملکرد، باید یک فیلتر در محدوده تاریخ اضافه کنید.
در اینجا یک پرس و جو نمونه است که یک ردیف را با تعداد کل کلیک ها در محدوده تاریخ مشخص شده برمی گرداند:
می‌توانید از قسمت‌های بخش‌ها برای تقسیم‌بندی در گزارش‌های عملکرد استفاده کنید. به عنوان مثال، پرس و جو برای marketing_method یک گزارش با یک ردیف برای هر روش بازاریابی، و معیارهایی که برای آن روش بازاریابی در بند SELECT مشخص می‌کنید، برمی‌گرداند.
فیلدهای بخش‌ها می‌توانند ویژگی‌های محصول (به عنوان مثال، offer_id ، brand ، و category ) یا ویژگی‌های رویداد (به عنوان مثال date و marketing_method ) باشند.
فیلدهای Segments مشابه GROUP BY در SQL عمل می کنند. فیلدهای بخش، معیارهای انتخابی را تقسیم می‌کنند و بر اساس هر بخش در عبارت SELECT گروه‌بندی می‌شوند.
در اینجا یک جستجوی نمونه وجود دارد که کلیک‌ها را در هر روز، به ترتیب نزولی بر اساس clicks ، در شرایط اضافه شده در محدوده تاریخ برمی‌گرداند. فقط ردیف هایی که حداقل یکی از معیارهای درخواستی آنها غیر صفر باشد، برگردانده می شوند.
پاسخ نمونه زیر نشان می‌دهد که تاجر 1546 کلیک روی همه محصولات، در همه روش‌های بازاریابی، در 1 دسامبر 2023، و 829 کلیک روی همه محصولات، در همه روش‌های بازاریابی، در 2 دسامبر 2023 داشته است. تاجر هیچ کلیکی روی آن نداشت. 3 دسامبر 2023، بنابراین چیزی برای آن تاریخ برگردانده نمی شود.
همانند گزارش‌های سفارشی در Merchant Center، می‌توانید با Merchant Reports API چندین بخش را در یک جستار مشخص کنید.
در اینجا یک جستجوی نمونه وجود دارد که کلیک‌ها را برای همه محصولات در حساب شما در یک دوره 30 روزه برمی‌گرداند که بر اساس marketing_method و offer_id تقسیم‌بندی شده است:
زبان پرس و جو Merchant Center از تقسیم بندی معیارها بر اساس دو گروه از ویژگی ها پشتیبانی می کند که می توانید برای سازماندهی موجودی خود تعریف کنید:
سطوح دسته
دسته بندی ها از طبقه بندی محصولات گوگل . اگر هیچ کدام ارائه نشده باشد، ممکن است Google به طور خودکار دسته را به محصول شما اختصاص دهد یا دسته بندی ارائه شده را بیشتر اصلاح کند.
هر دو ویژگی دسته و نوع محصول در یک سلسله مراتب با سطوح چندگانه سازماندهی شده اند. مشخصات محصول هر سطح را با کاراکتر > جدا می کند، اما شما هر سطح از سلسله مراتب را به طور جداگانه در گزارش ها انتخاب می کنید.
به عنوان مثال، محصولی را با سطوح نوع محصول زیر در نظر بگیرید:
معیارهای قیمت، مانند conversion_value ، با استفاده از نوع Price نشان داده می‌شوند. اگر معیار در چند ارز موجود باشد، ارزش هر ارز در یک ردیف جداگانه برگردانده می‌شود. به عنوان مثال، پرس و جو زیر:
اگر در یک جستار هم معیارهای قیمتی و هم غیرقیمتی را درخواست کنید، معیارهای قیمت در ردیف‌های نتیجه جداگانه از معیارهای غیرقیمتی، یک ردیف نتیجه برای هر کد ارز، برگردانده می‌شوند. به عنوان مثال، پرس و جو زیر:
تاریخ آخرین بهروزرسانی 2025-08-08 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-08 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe Merchant API provides performance reports that allow you to query metrics like clicks and impressions for specified date ranges using SQL-like syntax.\u003c/p\u003e\n"],["\u003cp\u003eReports can be segmented by product attributes (e.g., offer_id, brand) or event attributes (e.g., date, marketing_method) for granular analysis, similar to a SQL \u003ccode\u003eGROUP BY\u003c/code\u003e clause.\u003c/p\u003e\n"],["\u003cp\u003ePrice metrics, like \u003ccode\u003econversion_value\u003c/code\u003e, are returned in separate rows for each currency if available, potentially resulting in multiple rows for a single product or event.\u003c/p\u003e\n"],["\u003cp\u003eYou must specify the data to be returned in the \u003ccode\u003eSELECT\u003c/code\u003e clause, wildcards are not allowed, and segment fields require accompanying metrics to avoid errors.\u003c/p\u003e\n"],["\u003cp\u003eCategory and product type segments use a hierarchical structure, with each level returned in its own field, enabling detailed product performance analysis based on your inventory organization.\u003c/p\u003e\n"]]],["The Merchant API provides performance reports accessible via `product_performance_view`. Users query for specific metrics like `clicks` and `impressions` within a date range, using `SELECT` and `WHERE` clauses. Segments, including product and event attributes, allow data grouping, similar to SQL's `GROUP BY`. Reports can show clicks by date, marketing method, or offer ID. Category and product type can segment metrics. Price metrics are shown with multiple currencies, in separate rows. All selected fields are returned in the response, even if they have default or zero values.\n"],null,["# Performance reports\n\nThe Merchant API offers performance reports, for example\n[`product_performance_view`](/merchant/api/reference/rest/reports_v1/accounts.reports/search#productperformanceview).\nThis page explains the structure of performance reports.\n\nMetrics\n-------\n\nYou can query for metrics (for example, `clicks` and `impressions`) that you\nwant returned. You must add a filter on the date range to query the Reports\nservice for performance data.\n\nHere's a sample query that returns a single row, with the total number of clicks\nwithin the specified date range: \n\n SELECT clicks\n FROM product_performance_view\n WHERE date BETWEEN '2023-12-01' AND '2023-12-21'\n\nYou must specify the data you want returned. Wildcards (for example, `SELECT\n*`) return an error.\n\nThe following sample response shows that the merchant has had 4,440 total\nclicks, across all products, across all marketing methods, between December 1st,\n2023 and December 21st, 2023. \n\n {\n \"results\": [\n {\n \"productPerformanceView\": {\n \"clicks\": \"4,440\"\n }\n }\n ]\n }\n\n| **Key Point:** If you don't select any segments fields in your query, you only receive one row of metrics.\n\nSegments\n--------\n\nYou can use [segments\nfields](/merchant/api/guides/reports/query-language#segments) for\nsegmentation in [performance\nreports](/merchant/api/guides/reports/evaluate-products#measure_performance).\nFor example, querying for `marketing_method` returns a report with a row for\neach marketing method, and the\n[metrics](/merchant/api/guides/reports/query-language#metrics) that you\nspecify for that marketing method in the `SELECT` clause.\n\nSegments fields can be product attributes (for example, `offer_id`, `brand`, and\n`category`) or event attributes (for example `date` and `marketing_method`).\n\nSegments fields act similarly to a `GROUP BY` in SQL. Segments fields split the\nselected metrics, grouping by each segment in the `SELECT` clause.\n\nHere's a sample query that returns clicks per day, in descending order by\n`clicks`, within the added condition of a date range. Only rows where at least\none requested metric is non-zero are returned. \n\n SELECT\n date,\n clicks\n FROM product_performance_view\n WHERE date BETWEEN '2023-12-01' AND '2023-12-03'\n ORDER BY clicks DESC\n\nThe following sample response shows that the merchant had 1,546 clicks across\nall products, across all marketing methods, on December 1st, 2023, and 829\nclicks across all products, across all marketing methods, on December 2nd, 2023.\nThe merchant had no clicks on December 3rd, 2023, so nothing is returned for\nthat date. \n\n {\n \"results\": [\n {\n \"productPerformanceView\": {\n \"date\": {\n \"year\": 2023,\n \"month\": 12,\n \"day\": 1\n },\n \"clicks\": \"1546\"\n }\n },\n {\n \"productPerformanceView\": {\n \"date\": {\n \"year\": 2023,\n \"month\": 12,\n \"day\": 2\n },\n \"clicks\": \"829\"\n }\n }\n ]\n }\n\n| **Key Point:** You can only select specific segments fields if you also select metrics. If you don't select any metrics in your query, the Merchant Reports API returns an error.\n\nAs with custom reports in the Merchant Center, you can specify multiple segments\nin the same query with the Merchant Reports API.\n\nHere's a sample query that returns the clicks for all products in your account\nduring a 30-day period, segmented by `marketing_method` and `offer_id`: \n\n SELECT marketing_method, offer_id, clicks\n FROM product_performance_view\n WHERE date BETWEEN '2023-11-01' AND '2023-11-30'\n\nThe response from this query includes a row for each combination of `offer_id`\nand `marketing_method`, with the number of clicks for that combination: \n\n {\n \"results\": [\n {\n \"productPerformanceView\": {\n \"marketingMethod\": \"ADS\",\n \"offerId\": \"12345\",\n \"clicks\": \"38\"\n }\n },\n {\n \"productPerformanceView\": {\n \"marketingMethod\": \"ADS\",\n \"offerId\": \"12346\",\n \"clicks\": \"125\"\n }\n },\n {\n \"productPerformanceView\": {\n \"marketingMethod\": \"ORGANIC\",\n \"offerId\": \"12346\",\n \"clicks\": \"23\"\n }\n },\n {\n \"productPerformanceView\": {\n \"marketingMethod\": \"ADS\",\n \"offerId\": \"12347\",\n \"clicks\": \"8\"\n }\n },\n {\n \"productPerformanceView\": {\n \"marketingMethod\": \"ORGANIC\",\n \"offerId\": \"12347\",\n \"clicks\": \"3\"\n }\n }\n ]\n }\n\n| **Caution:** Since a new row is returned for each combination of segments fields in your `SELECT` clause, the total number of rows in your response increases exponentially with each additional segments field.\n\n### Category and product type\n\nThe [Merchant Center Query\nLanguage](/merchant/api/guides/reports/query-language) supports segmenting\nmetrics by two groups of attributes that you can define to organize your\ninventory:\n\nCategory levels\n: Categories from [Google's product\n taxonomy](//support.google.com/merchants/answer/6324436). Google might\n auto-assign the category to your product if none was provided, or further\n refine the provided category.\n\nProduct type levels\n: Product types that [you assign based on your\n categorization](//support.google.com/merchants/answer/6324406). Unlike the\n category levels, there is no predefined set of supported values.\n\nBoth the category and product type attributes are organized in a hierarchy with\nmultiple levels. The [product\nspecification](//support.google.com/merchants/answer/7052112) separates each\nlevel with the `\u003e` character, but you select each level of the hierarchy\nseparately in reports.\n\nFor example, consider a product with the following product type levels: \n\n Home & Garden \u003e Kitchen & Dining \u003e Kitchen Appliances \u003e Refrigerators\n\nReports return each level in its own field:\n\n| Segment | Value |\n|-------------------|----------------------|\n| `product_type_l1` | `Home & Garden` |\n| `product_type_l2` | `Kitchen & Dining` |\n| `product_type_l3` | `Kitchen Appliances` |\n| `product_type_l4` | `Refrigerators` |\n\n### Currency and price metrics\n\nPrice metrics, such as `conversion_value`, are represented using the\n[`Price`](/merchant/api/reference/rest/Shared.Types/Price)\ntype. If the metric is available in multiple currencies, the value for each\ncurrency is returned in a separate row. For example, the following query: \n\n SELECT conversion_value\n FROM product_performance_view\n WHERE date = '2023-11-01'\n\nreturns the following results: \n\n {\n \"results\": [\n {\n \"productPerformanceView\": {\n \"conversionValue\": {\n \"amountMicros\": \"150000000\",\n \"currencyCode\": \"USD\"\n }\n }\n },\n {\n \"productPerformanceView\": {\n \"conversionValue\": {\n \"amountMicros\": \"70000000\",\n \"currencyCode\": \"CAD\"\n }\n }\n }\n ]\n }\n\nIf you request both price and non-price metrics in a query, price metrics are\nreturned in separate result rows from non-price metrics, one result row per\ncurrency code. For example, the following query: \n\n SELECT conversions, conversion_value\n FROM product_performance_view\n WHERE date = '2020-11-01'\n\nreturns the following response: \n\n {\n \"results\": [\n {\n \"productPerformanceView\": {\n \"conversions\": \"27\",\n \"conversionValue\": {\n \"amountMicros\": \"0\",\n \"currencyCode\": \"\"\n }\n }\n },\n {\n \"productPerformanceView\": {\n \"conversions\": \"0\",\n \"conversionValue\": {\n \"amountMicros\": \"150000000\",\n \"currencyCode\": \"USD\"\n }\n }\n },\n {\n \"productPerformanceView\": {\n \"conversions\": \"0\",\n \"conversionValue\": {\n \"amountMicros\": \"70000000\",\n \"currencyCode\": \"CAD\"\n }\n }\n }\n ]\n }\n\nAll fields you select are returned in the response, even if their value is still\nthe default value or zero.\n\nFor more information about the fields available for query, see [Fields in `productPerformanceView` table](/merchant/api/reference/rest/reports_v1/accounts.reports#ProductPerformanceView.FIELDS)."]]
