בקשת דוחות
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
אחרי שמגדירים את אפליקציית הלקוח כמו שמתואר באפליקציה הראשונה שלי, אפשר להשתמש ב-Search Ads 360 API
כדי לבקש דוחות ולהוריד אותם. ניתן לשלוח כל אחד מסוגי הבקשות הבאים:
- סינכרוני
נדרשת רק בקשה אחת והחזרת הדוח בתגובה בפורמט JSON. בקשות סינכרוניות:
אם מבקשים דוחות גדולים של מפרסם או חשבון מנוע חיפוש, מומלץ להשתמש
בגישה האסינכרונית.
- אסינכרוני
כדי להשתמש בדוח, צריך לשלוח בקשה ראשונית שבה יצוין הנתונים
שרוצים שיופיעו בדוח. לאחר מכן, שולחים בקשות נוספות לסקר ב-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 בדוח של מילות מפתח עם טווח התאריכים 2013-01-01 עד 71-01-2013, ה-API יחזיר שבע שורות לכל מילת מפתח, שכל אחת מהן תואמת ליום אחד ומציגה מדדים לאותו יום. מידע נוסף זמין בקטע דוחות מפולחים.
סוגי מטבעות
בבקשת הדיווח יש לציין את המטבע של הנתונים הכספיים (שני מאפיינים כמו dailyBudget וגם מדדים כמו
cost). אפשר לציין אחת מהאפשרויות הבאות:
- המטבע של הסוכנות, אם הדוח מסווג
לחשבון של סוכנות, מפרסם או מנוע חיפוש.
- המטבע של המפרסם, אם הדוח מוגבל לחשבון של מפרסם או לחשבון מנוע חיפוש.
- המטבע של חשבון מנוע החיפוש, אם הדוח מוגבל לחשבון מנוע חיפוש.
- USD
יש להשתמש במאפיין הבקשה Reports.request.statisticsCurrency
כדי לציין מטבע.
בדוח עצמו יצוין המטבע בנכס Reports.statisticsCurrencyCode.
אזור זמן
המדדים של Search Ads 360 נשמרים בתאריכים ללא אזורי זמן. התאריכים האלה תואמים לאזור הזמן
של חשבון מנוע החיפוש במדדי מנוע החיפוש (כמו קליקים, חשיפות וביקורים)
ואזור הזמן ברשת Campaign Manager למדדי המרות (כמו פעולות,
עסקאות והכנסות). כשכל מדד בדוח מגיע מאותו אזור זמן, אזור הזמן הזה יוחזר בבקשה. אחרת, לא יוחזר אזור זמן.
הבקשות שלכם יכולות לגרום ל-Reports.request.verifySingleTimeZone: true
להיכשל בדוחות שנכשלו עם מדדים מכמה אזורי זמן.
אם כל המדדים בדוח הם מאזור זמן אחד, אזור הזמן הזה
יוחזר ב-Reports.statisticsTimeZoneReports.
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-29 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-29 (שעון UTC)."],[[["\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)."]]
