The code samples below provide examples of common reporting functions using the AdWords API. Client Library.
Download a criteria performance report with AWQL
' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
' http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.Util.Reports
Imports Google.Api.Ads.AdWords.v201809
Imports Google.Api.Ads.Common.Util.Reports
Imports System.IO
Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
''' <summary>
''' This code example gets and downloads a criteria Ad Hoc report from an AWQL
''' query. See https://developers.google.com/adwords/api/docs/guides/awql for
''' AWQL documentation.
''' </summary>
Public Class DownloadCriteriaReportWithAwql
Inherits ExampleBase
''' <summary>
''' Main method, to run this code example as a standalone application.
''' </summary>
''' <param name="args">The command line arguments.</param>
Public Shared Sub Main(ByVal args As String())
Dim codeExample As New DownloadCriteriaReportWithAwql
Console.WriteLine(codeExample.Description)
Try
Dim fileName As String = "INSERT_OUTPUT_FILE_NAME"
codeExample.Run(New AdWordsUser, fileName)
Catch e As Exception
Console.WriteLine("An exception occurred while running this code example. {0}",
ExampleUtilities.FormatException(e))
End Try
End Sub
''' <summary>
''' Returns a description about the code example.
''' </summary>
Public Overrides ReadOnly Property Description() As String
Get
Return _
"This code example gets and downloads a criteria Ad Hoc report from an AWQL" &
" query. See https://developers.google.com/adwords/api/docs/guides/awql for" &
" AWQL documentation."
End Get
End Property
''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
''' <param name="fileName">The file to which the report is downloaded.
''' </param>
Public Sub Run(ByVal user As AdWordsUser, ByVal fileName As String)
Dim query As String = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " &
"Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " &
"WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS"
Dim filePath As String = ExampleUtilities.GetHomeDir() + Path.DirectorySeparatorChar &
fileName
Try
Dim utilities As New ReportUtilities(user, "v201809", query,
DownloadFormat.GZIPPED_CSV.ToString())
Using reportResponse As ReportResponse = utilities.GetResponse()
reportResponse.Save(filePath)
End Using
Console.WriteLine("Report was downloaded to '{0}'.", filePath)
Catch e As Exception
Throw New System.ApplicationException("Failed to download report.", e)
End Try
End Sub
End Class
End Namespace
Download a criteria performance report using selectors
' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
' http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.Util.Reports
Imports Google.Api.Ads.AdWords.v201809
Imports Google.Api.Ads.Common.Util.Reports
Imports System.IO
Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
''' <summary>
''' This code example gets and downloads a criteria Ad Hoc report from an XML
''' report definition.
''' </summary>
Public Class DownloadCriteriaReportWithSelector
Inherits ExampleBase
''' <summary>
''' Main method, to run this code example as a standalone application.
''' </summary>
''' <param name="args">The command line arguments.</param>
Public Shared Sub Main(ByVal args As String())
Dim codeExample As New DownloadCriteriaReportWithSelector
Console.WriteLine(codeExample.Description)
Try
Dim fileName As String = "INSERT_OUTPUT_FILE_NAME"
codeExample.Run(New AdWordsUser, fileName)
Catch e As Exception
Console.WriteLine("An exception occurred while running this code example. {0}",
ExampleUtilities.FormatException(e))
End Try
End Sub
''' <summary>
''' Returns a description about the code example.
''' </summary>
Public Overrides ReadOnly Property Description() As String
Get
Return _
"This code example gets and downloads a criteria Ad Hoc report from an XML " &
"report definition."
End Get
End Property
''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
''' <param name="fileName">The file to which the report is downloaded.
''' </param>
Public Sub Run(ByVal user As AdWordsUser, ByVal fileName As String)
Dim definition As New ReportDefinition
definition.reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT"
definition.reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT
definition.downloadFormat = DownloadFormat.GZIPPED_CSV
definition.dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS
' Create the selector.
Dim selector As New Selector
selector.fields = New String() _
{"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria",
"FinalUrls", "Clicks", "Impressions", "Cost"}
selector.predicates = New Predicate() { _
Predicate.In("Status",
New String() _
{"ENABLED", "PAUSED"})
}
definition.selector = selector
' Optional: Include zero impression rows.
DirectCast(user.Config, AdWordsAppConfig).IncludeZeroImpressions = True
' Optional: You can also skip the report headers, column headers and
' report summary etc. to make the report parsing simpler.
' DirectCast(user.Config, AdWordsAppConfig).SkipColumnHeader = True
' DirectCast(user.Config, AdWordsAppConfig).SkipReportHeader = True
' DirectCast(user.Config, AdWordsAppConfig).SkipReportSummary = True
Dim filePath As String = ExampleUtilities.GetHomeDir() & Path.DirectorySeparatorChar &
fileName
Try
Dim utilities As New ReportUtilities(user, "v201809", definition)
Using reportResponse As ReportResponse = utilities.GetResponse()
reportResponse.Save(filePath)
End Using
Console.WriteLine("Report was downloaded to '{0}'.", filePath)
Catch e As Exception
Throw New System.ApplicationException("Failed to download report.", e)
End Try
End Sub
End Class
End Namespace
Get the report fields from a report
' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
' http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201809
Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
''' <summary>
''' This code example gets report fields.
''' </summary>
Public Class GetReportFields
Inherits ExampleBase
''' <summary>
''' Main method, to run this code example as a standalone application.
''' </summary>
''' <param name="args">The command line arguments.</param>
Public Shared Sub Main(ByVal args As String())
Dim codeExample As New GetReportFields
Console.WriteLine(codeExample.Description)
Try
Dim reportType As ReportDefinitionReportType = CType(
[Enum].Parse(GetType(ReportDefinitionReportType), "INSERT_REPORT_TYPE_HERE"),
ReportDefinitionReportType)
codeExample.Run(New AdWordsUser, reportType)
Catch e As Exception
Console.WriteLine("An exception occurred while running this code example. {0}",
ExampleUtilities.FormatException(e))
End Try
End Sub
''' <summary>
''' Returns a description about the code example.
''' </summary>
Public Overrides ReadOnly Property Description() As String
Get
Return "This code example gets report fields."
End Get
End Property
''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
''' <param name="reportType">The report type to be run.</param>
Public Sub Run(ByVal user As AdWordsUser, ByVal reportType As ReportDefinitionReportType)
Using reportDefinitionService As ReportDefinitionService = CType(
user.GetService(
AdWordsService.v201809.ReportDefinitionService),
ReportDefinitionService)
' The type of the report to get fields for.
' E.g.: KEYWORDS_PERFORMANCE_REPORT
Try
' Get the report fields.
Dim reportDefinitionFields As ReportDefinitionField() =
reportDefinitionService.getReportFields(reportType)
If ((Not reportDefinitionFields Is Nothing) AndAlso
(reportDefinitionFields.Length > 0)) Then
' Display report fields.
Console.WriteLine("The report type '{0}' contains the following fields:",
reportType)
For Each reportDefinitionField As ReportDefinitionField In _
reportDefinitionFields
Console.Write("- {0} ({1})", reportDefinitionField.fieldName,
reportDefinitionField.fieldType)
If (Not reportDefinitionField.enumValues Is Nothing) Then
Console.Write(" := [{0}]",
String.Join(", ", reportDefinitionField.enumValues))
End If
Console.WriteLine()
Next
Else
Console.WriteLine("This report type has no fields.")
End If
Catch e As Exception
Throw New _
System.ApplicationException("Failed to retrieve fields for report type.",
e)
End Try
End Using
End Sub
End Class
End Namespace
Stream results from a report
' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
' http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.Util.Reports
Imports Google.Api.Ads.AdWords.Util.Reports.v201809
Imports Google.Api.Ads.AdWords.v201809
Imports Google.Api.Ads.Common.Util.Reports
Imports System.IO.Compression
Imports System.Xml
Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
''' <summary>
''' This code example streams the results of an ad hoc report, collecting
''' total impressions by network from each line. This demonstrates how you
''' can extract data from a large report without holding the entire result
''' set in memory or using files.
''' </summary>
Public Class StreamCriteriaReportResults
Inherits ExampleBase
''' <summary>
''' Main method, to run this code example as a standalone application.
''' </summary>
''' <param name="args">The command line arguments.</param>
Public Shared Sub Main(ByVal args As String())
Dim codeExample As New StreamCriteriaReportResults
Console.WriteLine(codeExample.Description)
Try
codeExample.Run(New AdWordsUser)
Catch e As Exception
Console.WriteLine("An exception occurred while running this code example. {0}",
ExampleUtilities.FormatException(e))
End Try
End Sub
''' <summary>
''' Returns a description about the code example.
''' </summary>
Public Overrides ReadOnly Property Description() As String
Get
Return "This code example streams the results of an ad hoc report, collecting" &
" total impressions by network from each line. This demonstrates how you" &
" can extract data from a large report without holding the entire result" &
" set in memory or using files."
End Get
End Property
''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
Public Sub Run(ByVal user As AdWordsUser)
' Create the query.
Dim query As ReportQuery = New ReportQueryBuilder() _
.Select("Id", "AdNetworkType1", "Impressions") _
.From(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT) _
.Where("Status").In("ENABLED", "PAUSED") _
.During(ReportDefinitionDateRangeType.LAST_7_DAYS) _
.Build()
Dim reportUtilities As New ReportUtilities(user, "v201809", query,
DownloadFormat.GZIPPED_XML.ToString())
Dim impressionsByAdNetworkType1 As New Dictionary(Of String, Long)
Try
Using response As ReportResponse = reportUtilities.GetResponse
Using gzipStream As GZipStream = New GZipStream(response.Stream,
CompressionMode.Decompress)
Using reader As XmlTextReader = New XmlTextReader(gzipStream)
While reader.Read
Select Case reader.NodeType
Case XmlNodeType.Element ' The node is an Element.
If reader.Name = "row" Then
ParseRow(impressionsByAdNetworkType1, reader)
End If
End Select
End While
End Using
End Using
End Using
Console.WriteLine("Network, Impressions")
For Each network As String In impressionsByAdNetworkType1.Keys
Console.WriteLine("{0}, {1}", network, impressionsByAdNetworkType1(network))
Next
Catch e As Exception
Throw New System.ApplicationException("Failed to download report.", e)
End Try
End Sub
''' <summary>
''' Parses a report row.
''' </summary>
''' <param name="impressionsByAdNetworkType1">The map that keeps track of
''' the impressions grouped by by ad network type1.</param>
''' <param name="reader">The XML reader that parses the report.</param>
Private Sub ParseRow(ByVal impressionsByAdNetworkType1 As Dictionary(Of String, Long),
ByVal reader As XmlTextReader)
Dim network As String = Nothing
Dim impressions As Long = 0
While reader.MoveToNextAttribute
Select Case reader.Name
Case "network"
network = reader.Value
Case "impressions"
impressions = Long.Parse(reader.Value)
End Select
End While
If Not (network Is Nothing) Then
If Not (impressionsByAdNetworkType1.ContainsKey(network)) Then
impressionsByAdNetworkType1(network) = 0
End If
impressionsByAdNetworkType1(network) += impressions
End If
End Sub
End Class
End Namespace
Stream results from a report as objects
' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
' http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.Util.Reports
Imports Google.Api.Ads.AdWords.Util.Reports.v201809
Imports Google.Api.Ads.AdWords.v201809
Imports Google.Api.Ads.Common.Util.Reports
Imports System.IO.Compression
Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
''' <summary>
''' This code example streams the results of an ad hoc report, collecting
''' total impressions by network from each line. This demonstrates how you
''' can extract data from a large report without holding the entire result
''' set in memory or using files.
''' </summary>
Public Class StreamCriteriaReportToPoco
Inherits ExampleBase
''' <summary>
''' Main method, to run this code example as a standalone application.
''' </summary>
''' <param name="args">The command line arguments.</param>
Public Shared Sub Main(ByVal args As String())
Dim codeExample As New StreamCriteriaReportToPoco
Console.WriteLine(codeExample.Description)
Try
codeExample.Run(New AdWordsUser)
Catch e As Exception
Console.WriteLine("An exception occurred while running this code example. {0}",
ExampleUtilities.FormatException(e))
End Try
End Sub
''' <summary>
''' Returns a description about the code example.
''' </summary>
Public Overrides ReadOnly Property Description() As String
Get
Return "This code example streams the results of an ad hoc report, collecting" &
" total impressions by network from each line. This demonstrates how you" &
" can extract data from a large report without holding the entire result" &
" set in memory or using files."
End Get
End Property
''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
Public Sub Run(ByVal user As AdWordsUser)
' Create the query.
Dim query As ReportQuery = New ReportQueryBuilder() _
.Select("Id", "AdNetworkType1", "Impressions") _
.From(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT) _
.Where("Status").In("ENABLED", "PAUSED") _
.During(ReportDefinitionDateRangeType.LAST_7_DAYS) _
.Build()
Dim reportUtilities As New ReportUtilities(user, "v201809", query,
DownloadFormat.GZIPPED_XML.ToString())
Dim impressionsByAdNetworkType1 As New Dictionary(Of String, Long)
Try
Using response As ReportResponse = reportUtilities.GetResponse
Using gzipStream As GZipStream = New GZipStream(response.Stream,
CompressionMode.Decompress)
' Deserialize the report into a list of CriteriaReportRow.
' You can also deserialize the list into your own POCOs as follows.
' 1. Annotate your class properties with ReportRow annotation.
'
' Public Class MyCriteriaReportRow
'
' <ReportColumn>
' Public Property KeywordID as Long
'
' <ReportColumn>
' Public Property Impressions as Long
' End Class
'
' 2. Deserialize into your own report rows.
'
' Dim report As New AwReport(Of CriteriaReportRow) _
' (New AwXmlTextReader(gzipStream), "Example")
Using report As New AwReport(Of CriteriaReportRow) _
(New AwXmlTextReader(gzipStream), "Example")
While report.MoveNext()
Console.WriteLine(report.Current.Impressions)
Console.Write(" ")
Console.Write(report.Current.KeywordId)
End While
End Using
End Using
End Using
Console.WriteLine("Network, Impressions")
For Each network As String In impressionsByAdNetworkType1.Keys
Console.WriteLine("{0}, {1}", network, impressionsByAdNetworkType1(network))
Next
Catch e As Exception
Throw New System.ApplicationException("Failed to download report.", e)
End Try
End Sub
End Class
Public Class CriteriaReportRow
Private _KeywordId As Long
Private _Impressions As Long
<ReportColumn("keywordID")>
Public Property KeywordId As Long
Get
Return _KeywordId
End Get
Set(value As Long)
_KeywordId = value
End Set
End Property
<ReportColumn("impressions")>
Public Property Impressions As Long
Get
Return _Impressions
End Get
Set(value As Long)
_Impressions = value
End Set
End Property
End Class
End Namespace
Stream results from a report as objects of a predefined report row type
' Copyright 2018 Google LLC
'
' Licensed under the Apache License, Version 2.0 (the "License");
' you may not use this file except in compliance with the License.
' You may obtain a copy of the License at
'
' http://www.apache.org/licenses/LICENSE-2.0
'
' Unless required by applicable law or agreed to in writing, software
' distributed under the License is distributed on an "AS IS" BASIS,
' WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
' See the License for the specific language governing permissions and
' limitations under the License.
Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.Util.Reports
Imports Google.Api.Ads.AdWords.Util.Reports.v201809
Imports Google.Api.Ads.AdWords.v201809
Imports Google.Api.Ads.Common.Util.Reports
Imports System.IO.Compression
Namespace Google.Api.Ads.AdWords.Examples.VB.v201809
''' <summary>
''' This code example streams the results of an ad hoc report, and
''' returns the data in the report as objects of a predefined report row type.
''' </summary>
Public Class StreamReportToPredefinedReportRowType
Inherits ExampleBase
''' <summary>
''' Main method, to run this code example as a standalone application.
''' </summary>
''' <param name="args">The command line arguments.</param>
Public Shared Sub Main(ByVal args As String())
Dim codeExample As New StreamReportToPredefinedReportRowType
Console.WriteLine(codeExample.Description)
Try
codeExample.Run(New AdWordsUser)
Catch e As Exception
Console.WriteLine("An exception occurred while running this code example. {0}",
ExampleUtilities.FormatException(e))
End Try
End Sub
''' <summary>
''' Returns a description about the code example.
''' </summary>
Public Overrides ReadOnly Property Description() As String
Get
Return "This code example streams the results of an ad hoc report, and " &
"returns the data in the report as objects of a predefined report row type."
End Get
End Property
''' <summary>
''' Runs the code example.
''' </summary>
''' <param name="user">The AdWords user.</param>
Public Sub Run(ByVal user As AdWordsUser)
' Create the query.
Dim query As String = "SELECT AccountCurrencyCode, AccountDescriptiveName" &
" FROM FINAL_URL_REPORT DURING LAST_7_DAYS"
Dim reportUtilities As New ReportUtilities(user, "v201809", query,
DownloadFormat.GZIPPED_XML.ToString())
Dim impressionsByAdNetworkType1 As New Dictionary(Of String, Long)
Try
Using response As ReportResponse = reportUtilities.GetResponse
Using gzipStream As GZipStream = New GZipStream(response.Stream,
CompressionMode.Decompress)
Using report As New AwReport(Of FinalUrlReportReportRow) _
(New AwXmlTextReader(gzipStream), "Example")
While report.MoveNext()
Console.WriteLine(report.Current.accountCurrencyCode)
Console.Write(" ")
Console.Write(report.Current.accountDescriptiveName)
End While
End Using
End Using
End Using
Console.WriteLine("Network, Impressions")
For Each network As String In impressionsByAdNetworkType1.Keys
Console.WriteLine("{0}, {1}", network, impressionsByAdNetworkType1(network))
Next
Catch e As Exception
Throw New System.ApplicationException("Failed to download report.", e)
End Try
End Sub
End Class
End Namespace