In the newest version of the API, v201201, we’ve added a feature to streamline the syncing of information in your DFP network to another system. Previously, this was possible but required repeatedly downloading the same objects to see if they had been modified. Now, a new PQL field exists, lastModifiedDateTime, which can be used to return objects based on their modification dates. Below is a PHP example that uses the latest client library to display all line items modified in the past 30 days.

// Get the LineItemService.
$lineItemService = $user->GetService('LineItemService', 'v201201');

// Calculate time from thirty days ago.
$thirtyDaysAgo = date(DateTimeUtils::$DFP_DATE_TIME_STRING_FORMAT,
    strtotime('-30 day'));

// Create bind variables.
$vars = MapUtils::GetMapEntries(array(
    'thirtyDaysAgo' => new TextValue($thirtyDaysAgo)));

// Create statement object to only select line items that
// have been modified in the last 30 days.
$filterStatement = new Statement(
    "WHERE lastModifiedDateTime >= :thirtyDaysAgo "
    . "LIMIT 500", $vars);

// Get line items by statement.
$page = $lineItemService->getLineItemsByStatement($filterStatement);

You will notice that we utilized a constant, DFP_DATE_TIME_STRING_FORMAT ('Y-m-d\TH:i:s'), from the library to easily format the date/time string. Also, keep in mind that the date and time specified should be in terms of the time zone that is configured for the network and any timezone specified in the string will be ignored by the server.

We hope you'll use this new feature to help save bandwidth and processing time. You can check out a full working example in PHP or other languages in our client libraries.

Feel free to leave us a comment on the forum with any feedback you have for the API or topics you would like to see in the discover series.

 - Paul Rashidi, DFP API Team

In the v201201 version of the API, we’ve added the ability to perform PQL filtering in reports. As an example of what you can do with this feature, you can now limit the report to only orders and line items you want to see. This will help shorten the report job processing time and reduces the size of the report generated. The following Java code snippet creates a report job to pull all the line items belonging to an order in your network:

Long orderId = Long.parseLong("INSERT_ORDER_ID_HERE");
// Create statement to filter for an order.
Statement filterStatement = new StatementBuilder(
    "WHERE ORDER_ID = :id").putValue("id", orderId).toStatement();

// Create report job.
ReportJob reportJob = new ReportJob();

// Create report query.
ReportQuery reportQuery = new ReportQuery();
reportQuery.setStatement(filterStatement);
reportQuery.setDateRangeType(DateRangeType.LAST_MONTH);
reportQuery.setDimensions(new Dimension[] {Dimension.LINE_ITEM});
reportQuery.setDimensionAttributes(new DimensionAttribute[] {
DimensionAttribute.ORDER_TRAFFICKER});
reportQuery.setColumns(
    new Column[] {Column.AD_SERVER_IMPRESSIONS, Column.AD_SERVER_REVENUE});
reportJob.setReportQuery(reportQuery);

The ‘ORDER_ID’ field in the WHERE clause is a dimension enumeration name. A full breakdown of the supported filter enumerations can be found in the documentation. We encourage the use of bind variables to build reusable filter statements, much like other services in the API where PQL is used. Whenever possible, try to filter on IDs rather than names (i.e. use CITY_CRITERIA_ID over CITY_NAME) since matching by name is case sensitive.

If you also specify the dateRangeType and dimensionFilters fields on the ReportQuery object, the filter statement will be applied in conjunction (in a logical AND) so that each entry in the report will match all of the filter criteria. You can check out a full working example in Java or language equivalent in our client libraries.

This is the first post in the Discover DFP API in v201201 series; our next post will cover syncing objects with the new lastModifiedDateTime field. Leave us a comment on the forum with any feedback you have for the API or topics you would like to see in the discover series.

 - Jeffrey Sham, DFP API Team

The newest version of the API, v201201, brings some frequently requested features including using date time strings in PQL statements, filtering objects based on last modified date and times, including a PQL statement to limit a report (such as just running a report for one order), and more. A full list of features can be found on our release notes page.

Filtering

In v201201, we’ve focused on improving filtering with PQL statements across the entire API. We’ve introduced a better way to do date time filtering, a new lastModifiedDateTime field to search on, and the ability to filter from within a report.

With the ability to filter by date and time fields directly in the PQL statement, you’ll now be able to limit the objects on the server, rather than fetch all line items and checking their startDateTime property one at a time. For example, if you want to retrieve all line items that started so far in January, include

startDateTime

as a predicate of your filter with a date and time string, e.g.

WHERE startDateTime >= ‘2012-01-01T00:00:00’

. Note here that the date and time are in ISO 8061 format, i.e.

YYYY-MM-DDThh:mm:ss

, and the time zone is assumed to be that of the network’s. You can also bind a DateTime object instead of using a string, i.e.

WHERE startDateTime > :dateTime

, where

:dateTime

is bound to a DateTimeValue.

We’ve also added the new lastModifiedDateTime field to companies, creatives, ad units, line item creative associations, line items, orders, and placements. Using this field, you can now query for objects that have changed recently. Combined with the new date and time filtering feature mentioned above, you will be able to pull all objects changed so far this year, e.g.

WHERE lastModifiedDateTime >= ‘2012-01-01T00:00:00’

. If you are a developing an application that has to keep in sync with changes made through the UI, only pulling down objects that have changed since your last fetch time will speed up your calls and decrease processing time.

Finally, one of the largest requests from our developers was to limit what data is returned from within a report. We’ve add the ability to define a PQL statement in a report definition to do just that. Now when you create a report, you’ll be able to supply statements to limit it to just one order, e.g.

WHERE orderId = :orderId

, or with only one salesperson as well, e.g.

WHERE orderId = :orderId AND salespersonId = :salespersonId

.

Creatives

In v201102, we’ve added three new creative types that are only available to small business networks:

• FlashExpandableCreative - an expandable creative where the collapsed size is a Flash SWF file and the expanded size is another Flash SWF file.
• FlashPushdownCreative - a creative that pushes page content down when the creative expands.
• TextAdCreative - a text-based creative.

Teams

We’ve introduced a new service with this version, TeamService, which lets you group users into teams. Although currently not editable via the API, teams will be used to limit access to entities such as companies, inventory, and orders.

Coming soon

Over the next few weeks, you’ll learn about all of the features a bit more in the Discover v201201 series starting first with a discussion of filtering and syncing best practices. Let us know if you want to see anything else on our forum.

- Adam Rogal, DFP API Team