Discover v201003: Migrating your Account Structure Reports

Account structure report is one of the popular report formats in v13 of the AdWords API. This report allows you to download all the account attributes in a single report without performance details. A common use of account structure reports is to sync a local database against the AdWords server without using more expensive get() API calls.

Despite being a useful report format, account structure report is a specialized report format available only through the AdWords API. We designed the new API such that standard report formats can support your needs rather than creating additional specialized report types. Therefore, the new AdWords API doesn’t have a separate account structure report type, but you can use the existing report types supported by ReportDefinitionService to download the same data. This blog post discusses how this can be done, so that you can migrate your existing account structure reports to the v201003 version of the AdWords API. This blog post assumes you are familiar with the usage of ReportDefinitionService, if not, we suggest that you read our introductory blog post first.

Retrieving campaign structure information

You can download all campaigns in an account in the v201003 version of the AdWords API using CAMPAIGN_PERFORMANCE_REPORT. The xml request for adding the report definition is shown below:

<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003">
  <operations>
    <operator>ADD</operator>
    <operand>
      <selector>
        <fields>Id</fields>
        <fields>Name</fields>
        <fields>Status</fields>
        <fields>Amount</fields>
        </selector>
      <reportName>Campaign performance report #1277301277814.61</reportName>
      <reportType>CAMPAIGN_PERFORMANCE_REPORT</reportType>
      <dateRangeType>TODAY</dateRangeType>
      <downloadFormat>XML</downloadFormat>
    </operand>
  </operations>
</mutate>

Retrieving the ad group structure information

You can download all adgroups in an account in the v201003 version of the AdWords API using ADGROUP_PERFORMANCE_REPORT. The xml request for adding the report definition is shown below:

<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003">
  <operations>
    <operator>ADD</operator>
    <operand>
      <selector>
        <fields>Id</fields>
        <fields>Name</fields>
        <fields>Status</fields>
        <fields>CampaignId</fields>
      </selector>
      <reportName>AdGroup performance report #1277302184111.48</reportName>
      <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
      <dateRangeType>TODAY</dateRangeType>
      <downloadFormat>XML</downloadFormat>
    </operand>
  </operations>
</mutate>

If required, you can restrict the report to contain ad groups from only a particular campaign by setting a Predicate. A code example showing the usage of Predicate can be found here.

Retrieving the ad structure information

You can download all ads in an account in the v201003 version of the AdWords API using AD_PERFORMANCE_REPORT. The xml request for adding the report definition is shown below:

<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003">
  <operations>
    <operator>ADD</operator>
    <operand>
      <selector>
        <fields>Id</fields>
        <fields>Headline</fields>
        <fields>Description1</fields>
        <fields>Description2</fields>
        <fields>DisplayUrl</fields>
        <fields>Url</fields>
        <fields>Status</fields>
        <fields>AdGroupId</fields>
      </selector>
      <reportName>Ad performance report #1277303749892.73</reportName>
      <reportType>AD_PERFORMANCE_REPORT</reportType>
      <dateRangeType>TODAY</dateRangeType>
      <downloadFormat>XML</downloadFormat>
    </operand>
  </operations>
</mutate>

If required, you can restrict the report to contain ads from only a particular ad group by setting a Predicate.

Retrieving keyword and placement structure information

You can download all keywords in an account in the v201003 version of the AdWords API using KEYWORD_PERFORMANCE_REPORT. Similarly, all placements can be downloaded using MANAGED_PLACEMENTS_PERFORMANCE_REPORT. The xml requests for adding the keyword performance report definition are shown below:

<mutate xmlns="https://adwords.google.com/api/adwords/cm/v201003">
  <operations>
    <operator>ADD</operator>
    <operand>
      <selector>
        <fields>AdGroupId</fields>
        <fields>Id</fields>
        <fields>KeywordText</fields>
        <fields>KeywordMatchType</fields>
        <fields>IsNegative</fields>
      </selector>
      <reportName>Keyword performance report #1277353190509.28</reportName>
      <reportType>KEYWORDS_PERFORMANCE_REPORT</reportType>
      <dateRangeType>TODAY</dateRangeType>
      <downloadFormat>XML</downloadFormat>
    </operand>
  </operations>
</mutate>

The xml for placement report is identical to the one shown above, except for the reportType field. Note that have to use the KeywordText field to get the placement url while running MANAGED_PLACEMENTS_PERFORMANCE_REPORT.

Putting it all together

Here’s a code example that puts everything together to download your account structure using reports. The code snippet for parsing xmls and copying streams has been excluded for brevity.

Click here to expand

public class Program {
  public static void main(String[] args) throws FileNotFoundException, IOException,
      ServiceException {
    AdWordsUser user = new AdWordsUser(); 
    // Download all campaigns.
    GetReport(user, ReportDefinitionReportType.CAMPAIGN_PERFORMANCE_REPORT,
        new String[] { "Id", "Name", "Status", "Amount" }, "AllCampaigns.xml");

    // Download all adgroups.
    GetReport(user, ReportDefinitionReportType.ADGROUP_PERFORMANCE_REPORT,
        new String[] { "Id", "Name", "Status", "CampaignId"}, "AllAdGroups.xml");

    // Download all ads.
    GetReport(user, ReportDefinitionReportType.AD_PERFORMANCE_REPORT,
        new String[] { "Id", "Headline", "Description1", "Description2", "DisplayUrl",
        "Url", "Status", "AdGroupId" }, "AllAds.xml");

    // Download all keywords.
    GetReport(user, ReportDefinitionReportType.KEYWORDS_PERFORMANCE_REPORT,
        new String[] { "AdGroupId", "Id", "KeywordText", "KeywordMatchType", "IsNegative"},
        "AllKeywords.xml");

    // Download all placements.
    GetReport(user, ReportDefinitionReportType.MANAGED_PLACEMENTS_PERFORMANCE_REPORT,
        new String[] { "AdGroupId", "Id", "KeywordText", "KeywordMatchType", "IsNegative"},
        "AllPlacements.xml");
  }
  
  public static void GetReport(AdWordsUser user, ReportDefinitionReportType reportType,
      String[] fields, String fileName) throws FileNotFoundException, IOException,
      ServiceException {
    long reportDefinitionId = GenerateReportDefinition(user, reportType, fields);
    DownloadReport(user, reportDefinitionId,
     fileName);
  }
  
  public static void DownloadReport(AdWordsUser user, long reportDefinitionId,
     String fileName) throws FileNotFoundException, IOException {
     String url = "https://adwords.google.com/api/adwords/reportdownload?__rd=" +
         reportDefinitionId;

    HttpURLConnection urlConn = (HttpURLConnection) new URL(url).openConnection();
    urlConn.setRequestMethod("GET");
    urlConn.setRequestProperty("Authorization", "GoogleLogin auth=" +
        user.getRegisteredAuthToken());

    if (user.getClientCustomerId() != null) {
      urlConn.setRequestProperty("clientCustomerId", user.getClientCustomerId());
    } else if (user.getClientEmail() != null) {
      urlConn.setRequestProperty("clientEmail", user.getClientEmail());
    } else {
      urlConn.setRequestProperty("clientEmail", user.getEmail());
    }

    urlConn.connect();
    writeStreamToStream(urlConn.getInputStream(), new FileOutputStream(new File(fileName)));
  }

  public static long GenerateReportDefinition(AdWordsUser user,
      ReportDefinitionReportType reportType, String[] fields) throws ApiException,
      RemoteException, ServiceException {
    // Get the ReportDefinitionService.
    ReportDefinitionServiceInterface reportDefinitionService = user
        .getService(AdWordsService.V201003.REPORT_DEFINITION_SERVICE);

    // Create selector.
    Selector selector = new Selector();
    selector.setFields(fields);

    // Create report definition.
    ReportDefinition reportDefinition = new ReportDefinition();
    reportDefinition.setReportName("Structure report demo - #" +
        System.currentTimeMillis());
    reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.TODAY);
    reportDefinition.setReportType(reportType);
    reportDefinition.setDownloadFormat(DownloadFormat.XML);
    reportDefinition.setSelector(selector);

    // Create operations.
    ReportDefinitionOperation operation = new ReportDefinitionOperation();
    operation.setOperand(reportDefinition);
    operation.setOperator(Operator.ADD);

    ReportDefinitionOperation[] operations = new ReportDefinitionOperation[] { operation };

    // Add report definition.
    ReportDefinition[] result = reportDefinitionService.mutate(operations);
    return result[0].getId();
  }
}

We've included support for ReportDefinitionService in all of our client libraries to help get you started, so please try it out and share your feedback with us on the forum or the projects' issue trackers.

-- Anash P. Oommen, AdWords API Team