درخواست گزارشات
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
API جدید Search Ads 360 Reporting اکنون در دسترس است. API جدید انعطاف‌پذیری بیشتری برای ایجاد گزارش‌های سفارشی و ادغام داده‌ها در برنامه‌ها و فرآیندهای گزارش‌دهی شما فراهم می‌کند. درباره انتقال و استفاده از
Search Ads 360 Reporting API جدید بیشتر بیاموزید.
پس از تنظیم برنامه مشتری خود همانطور که در My First App توضیح داده شده است، می توانید از Search Ads 360 API برای درخواست و دانلود گزارش ها استفاده کنید. شما می توانید یکی از انواع درخواست های زیر را ارائه دهید:
- همزمان
فقط به یک درخواست نیاز دارد و گزارش را در یک پاسخ با فرمت JSON برمی گرداند. درخواست های همزمان:
- فقط می‌تواند گزارش‌های حساب‌های آگهی‌دهنده و موتور را بازگرداند
- مشتری خود را مسدود کنید تا زمانی که Search Ads 360 گزارش را ایجاد کند
اگر گزارش‌های حساب موتور یا تبلیغ‌کننده بزرگ را درخواست می‌کنید، ما رویکرد ناهمزمان را توصیه می‌کنیم.
- نامتقارن
از شما می خواهد که یک درخواست اولیه ارسال کنید که داده های مورد نظر شما را در گزارش مشخص می کند. سپس درخواست‌های اضافی را برای نظرسنجی Search Ads 360 ارسال می‌کنید. وقتی Search Ads 360 تولید گزارش را به پایان می‌رساند، درخواست‌هایی برای دانلود گزارش به‌عنوان یک یا چند فایل ارسال می‌کنید. درخواست های ناهمزمان:
- می تواند هر نوع گزارشی را برگرداند
- گزارش های بسیار بزرگ را به چندین فایل تقسیم می کند
- گزارش ها را به صورت CSV یا TSV قالب بندی می کند
مدل داده: سطرها و ستون ها
Search Ads 360 داده ها را در یک گزارش در ردیف ها و ستون ها سازماندهی می کند. نوع گزارشی که درخواست می کنید ردیف هایی را که برگردانده می شوند تعیین می کند. به عنوان مثال، اگر درخواست شما گزارش کلمه کلیدی باشد، هر ردیف حاوی اطلاعاتی در مورد یک کلمه کلیدی خواهد بود. برای فهرستی از انواع گزارش به مرجع انواع گزارش مراجعه کنید. شما با نامگذاری هر ستون در درخواست گزارش خود مشخص می کنید کدام ستون ها را در گزارش می خواهید. برای فهرست ستون هایی که می توان برای هر نوع گزارش برگرداند، به مرجع انواع گزارش مراجعه کنید.
رفتارهای ستونی
رفتار یک ستون به نوع داده ای که ستون حاوی آن است بستگی دارد (مرجع انواع گزارش رفتار هر ستون را نشان می دهد):
ستون های مشخصه یک ستون ویژگی حاوی داده‌هایی است که یک موجودیت را در یک کمپین پیکربندی یا شناسایی می‌کند، مانند نام کمپین یا پیشنهاد کلمه کلیدی. Search Ads 360 API همیشه مقدار فعلی یک ستون مشخصه را بدون توجه به تاریخ یا محدوده تاریخی مشخص شده در یک درخواست برمی‌گرداند. به عنوان مثال، اگر دیروز پیشنهاد یک کلمه کلیدی را از 2.00 به 1.50 تغییر دهید و سپس گزارشی را برای داده های ماه گذشته درخواست کنید، این گزارش مقدار 1.50 را برای پیشنهاد کلمه کلیدی برمی گرداند.
ستون های متریک یک ستون متریک حاوی داده‌هایی درباره عملکرد کمپین شما است، مانند تعداد کلیک‌های روی یک تبلیغ، تعداد بازدیدهایی که توسط یک برچسب Floodlight ثبت شده است، یا درآمد. مگر اینکه محدوده زمانی یک روز را مشخص کنید ، API یک مقدار کل را برای ستون‌های متریک برمی‌گرداند. به عنوان مثال، اگر گزارشی را برای داده های ماه گذشته درخواست کنید، API کل تعداد کلیک های ماه گذشته را برمی گرداند.
ستون های بخش . یک ستون بخش داده ها را به ردیف های جداگانه تقسیم می کند. به عنوان مثال، date یک ستون بخش است که می توانید برای بسیاری از انواع گزارش ها مشخص کنید. اگر ستون date در گزارش کلمه کلیدی با محدوده تاریخ 01-01-2013 تا 07-01-2013 مشخص کنید، API هفت ردیف را برای هر کلمه کلیدی برمی گرداند که هر کدام مربوط به یک روز است و معیارهای آن روز را نمایش می دهد. به گزارش های تقسیم شده مراجعه کنید.
ارزها
درخواست گزارش شما برای مشخص کردن واحد پولی داده‌های پولی (هم ویژگی‌هایی مانند dailyBudget و هم معیارهایی مانند cost ) لازم است. می توانید یکی از موارد زیر را مشخص کنید:
- واحد پول آژانس، اگر گزارش به حساب آژانس، تبلیغ‌کننده یا موتور اختصاص داده شده باشد.
- واحد پول آگهی‌دهنده، اگر گزارش به حساب تبلیغ‌کننده یا موتور اختصاص داده شده باشد.
- واحد پول حساب موتور، در صورتی که گزارش در محدوده یک حساب موتور باشد.
- دلار آمریکا
از ویژگی Reports.request.statisticsCurrency request برای تعیین ارز استفاده کنید.
خود گزارش واحد پول را در ویژگی Reports.statisticsCurrencyCode نشان می دهد.
منطقه زمانی
معیارهای Search Ads 360 در تاریخ‌های بدون منطقه زمانی ذخیره می‌شوند. این تاریخ‌ها با منطقه زمانی حساب موتور برای معیارهای موتور (مانند کلیک‌ها، نمایش‌ها و بازدیدها) و منطقه زمانی شبکه مدیریت کمپین برای معیارهای تبدیل (مانند اقدامات، تراکنش‌ها و درآمد) مطابقت دارند. وقتی هر سنجه در یک گزارش از همان منطقه زمانی می آید، آن منطقه زمانی در درخواست بازگردانده می شود. در غیر این صورت، هیچ منطقه زمانی برگردانده نخواهد شد. درخواست‌های شما می‌توانند Reports.request.verifySingleTimeZone : true تا ناموفق که معیارهای بیش از یک منطقه زمانی را ارائه می‌دهند.
اگر همه معیارهای موجود در یک گزارش از یک منطقه زمانی باشند، آن منطقه زمانی در Reports.statisticsTimeZoneReports برگردانده می‌شود.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe new Search Ads 360 Reporting API offers enhanced flexibility for building custom reports and integrating data into your workflows.\u003c/p\u003e\n"],["\u003cp\u003eYou can make synchronous requests for quick advertiser and engine account reports, or asynchronous requests for larger reports and various report types.\u003c/p\u003e\n"],["\u003cp\u003eReports are organized into rows based on the report type and columns that you specify in your request, with attribute, metric, and segment columns behaving differently.\u003c/p\u003e\n"],["\u003cp\u003eWhen requesting reports, you need to specify the currency for monetary data, and Search Ads 360 handles time zones based on engine and conversion metric sources.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API allows custom report building and data integration. Reports can be requested synchronously (limited to advertiser/engine account reports, JSON format, blocking) or asynchronously (all report types, CSV/TSV format, multiple files). Data is organized in rows and columns; column behavior varies by type (attribute, metric, segment). Currency for monetary data must be specified and can be the agency's, advertiser's, or engine account's or USD. Time zones are relevant to metric dates.\n"],null,["# Request Reports\n\nThe new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the [new Search Ads 360 Reporting\nAPI](https://developers.google.com/search-ads/reporting/overview).\n\n\nAfter you've set up your client app as described in [My First App](/search-ads/v2/first-app), you can use the Search Ads 360 API\nto request and download reports. You can make either of the following types of\nrequests:\n\n**[Synchronous](/search-ads/v2/how-tos/reporting/synchronous-requests)**\n\n: Requires just a single request and returns the report in a JSON-formatted response. Synchronous requests:\n\n - Can return only [advertiser](/search-ads/v2/report-types/advertiser) and [engine account](/search-ads/v2/report-types/account) reports\n - Block your client until Search Ads 360 generates the report\n\n\n If you're requesting large advertiser or engine-account reports, we recommend the\n asynchronous approach.\n\n**[Asynchronous](/search-ads/v2/how-tos/reporting/asynchronous-requests)**\n\n: Requires you to send an initial request that specifies the data you want in the\n report. Then you send additional requests to poll Search Ads 360. When Search Ads 360 finishes generating the report,\n you send requests to download the report as one or more files. Asynchronous requests:\n\n - Can return any [report type](/search-ads/v2/report-types)\n - Shards very large reports into multiple files\n - Formats reports as CSV or TSV\n\n### Data model: rows and columns\n\nSearch Ads 360 organizes data in a report into rows and columns.\nThe type of report you request determines the **rows** that are returned.\nFor example, if your request a keyword report, each row will contain data about a single\nkeyword. See the [Report Types](/search-ads/v2/report-types)\nreference for a list of all report types.\nYou specify which **columns** you want in the report by naming each column\nin your report request. See the [Report\nTypes](/search-ads/v2/report-types) reference for the list of columns that can be returned for each report type.\n\n### Column behaviors\n\n\nThe behavior of a column depends on the type of data that the column\ncontains (the [Report Types](/search-ads/v2/report-types) reference\ndisplays each column's behavior):\n\n-\n **Attribute columns**. An attribute column contains data that configures\n or identifies an entity in a campaign, such as the campaign name or a keyword bid. The Search Ads 360 API\n always returns the current value for an attribute column, regardless of any date or\n date range specified in a request. For example, if you changed a keyword's bid from\n 2.00 to 1.50 yesterday and then request a report for last month's data, the report\n will return a value of 1.50 for the keyword bid.\n\n-\n **Metric columns** . A metric column contains data about your campaign's\n performance, such as the number of clicks on an ad, the number of visits as recorded\n by a Floodlight tag, or revenue. Unless you [specify a\n time range](/search-ads/v2/reference/reports#request.timeRange) of a single day, the API returns an aggregate value for metric columns. For\n example, if you request a report for last month's data, the API will return the total\n number of clicks for last month.\n\n-\n **Segment columns** . A segment column splits data into separate rows.\n For example, `date` is a segment column that you can specify for many\n types of reports. If you specify the `date` column in a keyword report\n with a date range 2013-01-01 to 2013-01-07, the API would return seven rows for each\n keyword, each corresponding to one day and displaying metrics for that day. See [Segmented\n Reports](/search-ads/v2/how-tos/reporting/segmented-reports).\n\n### Currencies\n\n\nYour report request is required to specify the currency of monetary data (both attributes like `dailyBudget` and metrics like\n`cost`). You can specify one of the following:\n\n- The agency's currency, if the report is [scoped](/search-ads/v2/reference/reports#request.reportScope) to an agency, advertiser, or engine account.\n- The advertiser's currency, if the report is scoped to an advertiser or engine account.\n- The engine account's currency, if the report is scoped to an engine account.\n- USD\n\n\nUse the [Reports.request.statisticsCurrency](/search-ads/v2/reference/reports#request.statisticsCurrency)\nrequest property to specify a currency.\n\n\nThe report itself will indicate the currency in the ` `[Reports.statisticsCurrencyCode](/search-ads/v2/reference/reports#statisticsCurrencyCode) property.\n\n### Time zone\n\n\nSearch Ads 360 metrics are stored in dates without time zones. These dates correspond to the engine\naccount time zone for engine metrics (such as clicks, impressions, and visits), and\nCampaign Manager network time zone for conversion metrics (such as actions,\ntransactions and revenue). When every metric in a report comes from the same time zone,\nthat time zone will be returned in the request. Otherwise, no time zone will be returned.\nYour requests can set [Reports.request.verifySingleTimeZone](/search-ads/v2/reference/reports#request.verifySingleTimeZone)`: true`\nto fail reports that present metric from more than one time zone.\n\n\nIf all metrics present in a report are from one time zone, that time zone is\nreturned in [Reports.statisticsTimeZoneReports](/search-ads/v2/reference/reports#statisticsTimeZone)."]]
