In this installment of the Discover DFP API v201111 series, we present new features we’ve added to reports in the API. In addition to merged ad server columns, which helps upgraded publishers reports on both DART and DFP ad servers, you can now use dimension attributes for greater control in reporting.

Dimension Attributes

Dimension attributes let you break down your report by additional fields associated with the dimension. For example, you can now add the trafficker, external ID, and order start date as dimension attributes associated to your order dimension in a delivery report. This is useful if you would like to see how each of your orders is doing and which trafficker was responsible for that order.

In the past, you would get this information by running a report for orders and then looking up the orders with Order Service to inspect the attributes. Now, it’s as simple as adding values to the dimensionAttributes field on your ReportQuery object and the corresponding fields will be integrated into the report. The following code snippet shows you how to create a report job with dimension attributes:
// Create report job.
ReportJob reportJob = new ReportJob();

// Create report query.
ReportQuery reportQuery = new ReportQuery();
reportQuery.setDateRangeType(DateRangeType.LAST_MONTH);
reportQuery.setDimensions(new Dimension[] {Dimension.ORDER});

// Set dimension attributes for order dimension.
reportQuery.setDimensionAttributes(new DimensionAttribute[] {
    DimensionAttribute.ORDER_TRAFFICKER,
    DimensionAttribute.ORDER_START_DATE_TIME,
    DimensionAttribute.ORDER_END_DATE_TIME});

// Set columns to report on.
reportQuery.setColumns(new Column[] {
    Column.AD_SERVER_IMPRESSIONS,
    Column.AD_SERVER_CLICKS});

reportJob.setReportQuery(reportQuery);
You can check out the full example in the RunDeliveryReportExample in the Java client library. Notice that you can only add dimension attributes for dimensions that you have in the report. For example, if you tried to add LINE_ITEM_EXTERNAL_ID, and you only have order (but not line item) as a dimension, you will get the following error:

ReportError.ATTRIBUTES_NOT_SUPPORTED_FOR_REQUEST

Be sure to check out our updated reporting examples in the client libraries and take a look at our documentation for a full mapping of supported dimension attributes and the fields they represent.

We are always looking for ways to improve the API and we’d love to get your feedback. Let us know what you’d like to see in the API or discussed in a blog post by posting on our forum. We’re also more than happy to chat during one of our office hours hangouts.