Creating Simple Scripts With the API

The DoubleClick for Advertisers (DFA) API provides a comprehensive set of services that can be used to create applications that mediate all of your interactions with your DoubleClick account. But the API doesn’t have to be used solely for making enterprise-level software solutions. Everyone, even DoubleClick clients who use the website interface for the majority of their trafficking needs, can create small scripts or programs to automate repetitive or laborious tasks. However, users of the website interface should first determine if exporting and importing Traffic Sheets could fulfil their needs. In either case, small API routines may be able to provide some value.

An example in code: Cleaning up inactive ads

One case where the API can really shine is cleaning up a campaign. If you’ve got particularly long-running campaigns, or if you frequently change the ads shown in your placements based on dates, you can clean up all of the ads that have stopped running by archiving them and unassigning them from their placements. Ads will be automatically set to inactive for various reasons, the most important being if they have passed a hard cut-off date or if they have reached their delivery goals.

Looking at a snippet of the code from a program that would accomplish this demonstrates the two important parts - generating a record set and looping through all the pages in a paged record set, making changes as necessary:

// Create Ad Search Criteria
AdSearchCriteria adCriteria = new AdSearchCriteria();
adCriteria.setPageSize(10);
adCriteria.setCampaignId(campaignId);

// Get ads.
AdRecordSet results = adService.getAds(adCriteria);
if (results.getRecords() == null || results.getRecords().length == 0) {
System.out.println("Found no ads associated with the given campaign.");
} else {
System.out.println(
"Found " + results.getTotalNumberOfRecords() + " ads associated with "
+ "this campaign.");

// Loop through all pages.
for (int i = 0; i <= results.getTotalNumberOfPages(); i++) {
if (i != 0) {
adCriteria.setPageNumber(i);
results = adService.getAds(adCriteria);
}
// For each ad, check to see if it should be modified.
for (AdBase ad : results.getRecords()) {
if (ad.isActive()) {
// This ad is still active. It will not be modified.
} else {
// This ad is inactive. It will be archived and removed from all
// placements and archived.
ad.setPlacementAssignments(new PlacementAssignment[] {});
ad.setArchived(true);
adService.saveAd(ad);
}
}
}
}

You can find a complete open source Java class that removes inactive ads from campaigns on our examples site.

Intended use of the API

It is important to realize that the API is not optimized for looping through all of the information in your account. It is possible to grab every advertiser you have, fetch every campaign for each advertiser, then look at each campaign’s ads, each ad’s creatives, etc. This is very slow, creates a lot of unnecessary traffic, and should always be avoided if possible. You should regularly take advantage of the options provided by each type of SearchCriteria object to focus in on the areas you need to see without forcing the API to return tons of extraneous information. The search criteria objects in each service are not identical; some allow you to narrow down your searches based on fields specific to what you are searching for. Understanding and using these extra fields will greatly speed up any applications you write that pull down a lot of data.

Going further

The basic pattern here is simple: generate the tightest record set as possible, page through the record set, check to see if each object is one you want to modify, and if so make the changes you want. You can create tools following the same pattern to do all sorts of repetitive tasks, such as mass renaming or replacing a placement assignment with another within all ads associated with the retired placement. If you frequently encounter situations where everything that matches some criteria needs to be altered, having a program or script like this on hand can save you a lot of time. Do note that the API already has operations for copying creatives, campaigns, and ads, so you do not need to create tools to make duplicates. These functions are provided and fast.

If you have any questions about tools like this, or if you can think of a task that is so common it should be part of the API, please bring your questions or ideas to the API forum.

- Joseph DiLallo, the DFA API Team