Discover v201101: Generic selectors

AdWords API v201101 changes the way you retrieve data using the get() method of most services. This blog post discusses the new feature in detail and highlights the changes you need to make in your code to migrate to generic selectors.

Introduction

Prior to v201101 of AdWords API, every service had its own selector to retrieve data using the get() method. For instance, to retrieve all active ad group criteria in an ad group, you would write your code as

// OLD CODE - v201008.
// Create selector.
AdGroupCriterionSelector selector = new AdGroupCriterionSelector();
selector.userStatuses = new UserStatus[] {UserStatus.ACTIVE};
 
// Create id filter.
AdGroupCriterionIdFilter idFilter = new AdGroupCriterionIdFilter();
idFilter.adGroupId = adGroupId;
 
selector.idFilters = new AdGroupCriterionIdFilter[] {idFilter};
 
// Get all ad group criteria.
AdGroupCriterionPage adGroupCriterionPage =
    adGroupCriterionService.get(selector);

While simple to use, since each service had its own selector class, you needed to know about selectors of each service with which you worked. Also, since filtering options were specified as member fields of the selector, adding support for new filtering involved changing the selector definition in the service. and hence could be done properly only across versions.

On the other hand, the selector model used by reports is much more flexible - you can specify a list of fields, provide any number of filtering conditions on any Filterable field using predicates, use multiple operators (unlike the implicit EQUALS operator in the code above) and so on. Also, since field names aren’t tied to a SOAP schema, it is easy to add new selectable and filterable fields. Additionally, the code you need to write to generate and download any report remains the same. In v201101, we decided to take this design and apply it across all services.

Using v201101 of AdWords API, you can retrieve all active ad group criterion in an ad group as follows:

// NEW CODE - v201101.
// Create a selector.
Selector selector = new Selector();
selector.fields = new string[] {"Id", "AdGroupId", "KeywordText", "Status"};
 
// Set filter conditions.
Predicate adGroupPredicate = new Predicate();
adGroupPredicate.field = "AdGroupId";
adGroupPredicate.@operator = PredicateOperator.EQUALS;
adGroupPredicate.values = new string[] {adGroupId.ToString()};
 
Predicate statusPredicate = new Predicate();
statusPredicate.field = "Status";
statusPredicate.@operator = PredicateOperator.EQUALS;
statusPredicate.values = new string[] {UserStatus.ACTIVE.ToString()};
 
selector.predicates = new Predicate[] {adGroupPredicate, statusPredicate};
 
// Get all ad group criteria.
AdGroupCriterionPage adGroupCriterionPage =
    adGroupCriterionService.get(selector);

Understanding selector properties

The main properties of the selector are:

Fields: When using generic selectors to retrieve an object, the server will not return every field of the object by default; it will return only the requested set of fields. Other fields in the object will be set as undefined/null depending on the programming language you use. You can use the Fields property to specify the list of fields to be returned. You can use any Selectable field from the entity here. For example, when using CampaignService, you can use any Selectable field from Campaign. Campaign.name is marked as a Selectable field, and its selector field name is specified as “Name”, so you can use that as an entry for Fields.

Note that when an object has a field that is a reference to another object, then that property may not be marked as Selectable. In such cases, its sub fields will be marked as Selectable. For example, Campaign.budget is a property of type Budget, so Campaign.budget is not a Selectable field. To retrieve a campaign’s budget fields, you have to request Selectable fields from the Budget object.

Predicates: You can use predicates to filter the returned data by field values. You can use any Filterable field from the entity in a predicate. You can also use various operators to specify the filtering condition. Also, when using multiple predicates in a single selector, the predicates are ANDed to evaluate the effective filter condition.

Each service provides a set of service-specific fields and generic selector fields that can be used with Predicates. E.g. you can use CampaignId as a predicate field with AdGroupAdService, even though CampaignId is not a member of AdGroupAd. For the list of all the generic selector fields, you can refer to the selector migration guide.

DateRange: You can provide an optional DateRange to control the date range for which the data is retrieved. Specifying a date range only affects the stats returned by the server (if applicable), not the actual entities being returned by the server. The date format for min and max fields have the format yyyymmdd. The date range should be in the range [19700101, 20380101].

Ordering: You can use the ordering field to specify the fields on which you want to sort the data (ascending or descending). The order in which you specify the OrderBy objects in the ordering field is significant; the first element specifies the primary sort order, the second element specifies the secondary sort order and so on.

Paging: You can use the paging field to specify the position from which to start returning results and the number of results to return per page.

Migrating from service-specific selectors to generic selectors

Service-specific selectors (e.g. CampaignSelector) aren’t supported from v201101 onwards, so you will have to modify your code to use generic selectors when migrating to v201101 of AdWords API. You can refer to the selector migration guide to get the field mapping for each service-specific selector. Also note that a few services do not use generic selectors yet. This will happen in a future version of AdWords API.

We have added support for generic selectors in all of our client libraries, so please take advantage of this new feature and share your feedback with us on the forum.

  --Anash P. Oommen, AdWords API Team