Imagine for a moment that you're a mobile line item. You've just been initialized locally, and all of a sudden you’re having an existential crisis -- what makes you, you? How are you different from all the other line items? Sure your associated creative might be a bit different from other line items and you might have a few extra impressions allotted to your goal, but what truly makes you... unique? In this series of posts, we'll take you on an incredible journey through a day in the life of a mobile line item -- from how to target mobile to the actual delivery on a device.

Adding mobile specific targeting

It all starts similarly enough: you need a name, an order ID, start and end dates, a goal, and all the usual suspects -- but wait, there's more! Instead of just having custom criteria, ad units, and geo-targeting, you find that you also have TechnologyTargeting fields specified, like:

• DeviceCategoryTargeting
• OperatingSystemTargeting
• MobileCarrierTargeting

Now, say you're being created as a line item to advertise Android tablet cases. It doesn't make much sense for you to be delivered to an iPad or an iPhone, so we need to add technology specific targeting.

To do so using Java, we would first set the DeviceCategory object with the targeting ID of the 'Tablet' category and the OperatingSystem object with the targeting ID of 'Android', both of which we'd pull from the PublisherQueryLanguage service:

    DeviceCategory deviceCategory = new DeviceCategory();
    OperatingSystem operatingSystem = new OperatingSystem();

    deviceCategory.setId(30002L);
    operatingSystem.setId(501013L);

These would then be set on the DeviceCategoryTargeting and OperatingSystemTargeting objects:

    DeviceCategoryTargeting deviceCategoryTargeting = new DeviceCategoryTargeting();
    OperatingSystemTargeting operatingSystemTargeting = new OperatingSystemTargeting();

    deviceCategoryTargeting.setTargetedDeviceCategories(new DeviceCategory[] {deviceCategory});
    operatingSystemTargeting.setOperatingSystems(new OperatingSystem[] {operatingSystem});

Finally, the Targeting object will have a TechnologyTargeting object set for DeviceCategoryTargeting and also OperatingSystemTargeting:

    TechnologyTargeting techTargeting = new TechnologyTargeting();
    technologyTargeting.setDeviceCategoryTargeting(deviceCategoryTargeting);
    technologyTargeting.setOperatingSystemTargeting(operatingSystemTargeting);

    Targeting targeting = new Targeting();
    targeting.setTechnologyTargeting(techTargeting);

Now what happens? You're a line item that has a bit of technology targeting specified, but where are you off to next? Stay tuned for what happens next in - 'A day in the life of a mobile line item, part 2.'

 - Nicholas Chen, DFP API Team

In v201311 we changed how the API returns locations to:

• More granularity in targeting 
• Streamlined code paths 
• Increased flexibility for handling location objects

Along with the update to location objects, we've also expanded the list of targetable locations far beyond what was previously available. If you look at new Geo_Target table - which replaces the individual City, Country, Metro, Postal Code, and Region tables - you’ll find that you now have far more control over where your ads will serve. In the past, the smallest location you could target was a city; now, you can target something as specific as an Airport.

Many of you have asked how to migrate from the deprecated PQL tables to the new Geo_Target table.

Instead of having a table for each geo locations type, we combine everything into a single table with the type defined as a new column. This not only makes things easier for you, it also allows us to add even more types of locations to target in the future without having to make new tables.

As far as how the old tables relate to the new Geo_Target table, the Country, City, Postal_Code, and Region tables will map to their respective namesake columns, with only the Metro table being different, now mapping to the more canonical DMA_Region. To see how simple it is to replicate the old behavior, look at this Python example that pulls down the targetable City locations.

If you’re not entirely sure how to break out your targeting into smaller geo locations, we’ve got you covered there too - instead of trying to make your own relational mapping between cities, metros, regions, and countries, the new Geo_Target table simplifies the task with the ParentIds field, which yields a list of parent location IDs that encompass a child location.

For the new year, make a resolution to switch over to the new Geo_Target table and reap the benefits thereafter.

 - Nicholas Chen, DFP API Team

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