How do I create an audience using the new Google Ads API?

[Jon Oler]

I am unable to create a new audience using the new Google Ads API. The release notes for version 0.6.0 of the API (https://developers.google.com/google-ads/api/docs/release-notes) claim that the ability to "Create audiences using UserListService" was added in this release. I am using version 0.6.0 of the java Google Ads SDK. Here is my code (it's groovy code using the java sdk, not Java code):

      // Look up an existing rule-based user list...

      UserList existingUserList = userListServiceClient.getUserList("customers/6257802538/userLists/4598470")

      // Use the rule-based user list I looked up to create a new user list. I need to clear some attributes to avoid API errors...

      UserList newUserList = UserList.newBuilder(existingUserList)

          .setName(StringValue.of("Oler user list test 1"))

          .clearId()

          .clearResourceName()

          .clearClosingReason()

          .build()

      UserListOperation userListOperation = UserListOperation.newBuilder()

          .setCreate(newUserList)

          .build()

      userListServiceClient.mutateUserLists('6257802538', [userListOperation])

Here is the API error I receive when I make this call:

errors {

  error_code {

    user_list_error: CONCRETE_TYPE_REQUIRED

  }

  message: "Concrete type of user list is required."

  trigger {

    string_value: ""

  }

  location {

    operation_index {

    }

  }

}

I get the same error when trying to create a LOGICAL user list instead of a RULE_BASED user list as I'm doing in the example. In my example code, I'm trying to copy an existing user list, but I've also tried creating the user list from scratch, and I received the exact same API error ("concrete type required"). I don't see where I can set things like the url on a rule-based user list or add references to other user lists when creating a logical user list. Is creating user lists really supported in 0.6.0 of the Google Ads API as the release notes indicate? If so, what am I doing wrong when I'm attempting to create these things?

[Dhanya Sundararaju (AdWords API Team)]

Hi Jon,

Sorry for the delay as I was checking with my team on this. Instead, you will need to create an Info object (e.g., CrmBasedUserListInfo) and set it to the UserList object via the setCrmBasedUserList() method. 

  CrmBasedUserListInfo userList = CrmBasedUserListInfo.newBuilder()

  .setUploadKeyType(CustomerMatchUploadKeyType.CONTACT_INFO)

                       ..

                       ..

      .build();

  

  UserList newUserList = UserList.newBuilder()

          .setName(StringValue.of("Oler user list test 1"))

          .setCrmBasedUserList(userList)

          .build();

    

  UserListOperation userListOperation = UserListOperation.newBuilder()

  .setCreate(newUserList)

          .build();

That is, steps similar toAddExpandedTextAds example.

Regards,

Dhanya, Google Ads API Team

[Jon Oler]

Hi Dhanya,

Thank you very much for your response. However, I still don't see how I can create the user lists I need to create with the new Google Ads API. I only see CrmBasedUserListInfo and SimilarUserListInfo classes in the 0.6.0 java sdk. As I mentioned in my original post, I'm trying to create RULE_BASED and LOGICAL user lists, not CRM or Similar user lists. For example, here's some code that creates an ExpressionBasedUserList using the current (old) AdWords API (this code actually works using the current SOAP AdWords java sdk):

    StringKey urlTypeKey = new StringKey("url__");

    StringRuleItem urlStringRuleItem = new StringRuleItem();

    urlStringRuleItem.setKey(urlTypeKey);

    urlStringRuleItem.setOp(StringRuleItemStringOperator.CONTAINS);

    urlStringRuleItem.setValue("oler.html");

    RuleItem urlRuleItem = new RuleItem();

    urlRuleItem.setStringRuleItem(urlStringRuleItem);

    RuleItemGroup urlItemGroup = new RuleItemGroup();

    urlItemGroup.setItems(new RuleItem[] {urlRuleItem});

    Rule rule = new Rule();

    rule.setGroups(new RuleItemGroup[] {urlItemGroup});

    ExpressionRuleUserList expressionUserList = new ExpressionRuleUserList();

    expressionUserList.setName("Oler test 1 7 day expression based user list");

    expressionUserList.setDescription("Oler test 1 expression based user list description");

    expressionUserList.setRule(rule);

    expressionUserList.setPrepopulationStatus(RuleBasedUserListPrepopulationStatus.REQUESTED);

    expressionUserList.setMembershipLifeSpan(7L);

    UserListOperation operation = new UserListOperation();

    operation.setOperand(expressionUserList);

    operation.setOperator(Operator.ADD);

    UserListReturnValue result =

        adwordsUserListServiceInterface.mutate(new UserListOperation[] {operation});

I'd like to know how to do this exact same thing using the new Google Ads API. As I mentioned previously, the release notes for version 0.6.0 of the new Google Ads API states that the ability to "Create audiences using UserListService" was added in this release. Can you please tell me how I can create an ExpressionRuleUserList and a LogicalUserList using the new Google Ads API?

Thanks again,

Jon

[Dhanya Sundararaju (AdWords API Team)]

Hi Jon,

Currently, only CRMBased User Lists and Similar user lists are supported as stated in this section of the guide. Please keep an eye on the blog for updates on future releases.

[Jon Oler]

Thanks again for the response, Dhanya. I now have my answer. 

I realize that the new API is in beta and that the full API that includes all the functionality of the old SOAP API is supposed to be released this quarter. That said, I feel like both the API docs and the release notes could be clearer on this point. 

As I mentioned earlier, the release notes just state that as of version 0.6.0, this functionality was added to the API: "Create audiences using UserListService". Any reader of the release notes is naturally going to assume that all types of audiences can now be created with the API. Just changing this to "Create CRMBasedUserList and SimilarUserList audiences using UserListService. Support for other types of audiences will be added in future releases".would make things much clearer.

The only things in the API docs that I can find that you referenced state:

Union field user_list. The user list.

Exactly one must be set. user_list can be only one of the following:

 

crm_based_user_list

similar_user_list

 

Again, no mention is made of the other possible types of user lists, so the reader of the API docs is left to wonder whether other types of users lists are actually supported or not. The fact that it is possible to read (what I now understand are incomplete versions) these all types of users lists (including ExpressionBasedUserList, LogicalUserList, etc.) also leads API users to believe that the API has full support for all types of user lists. Just adding a statement like "Support for creating other types of user lists will be added in future versions of the API " to this part of your API docs would make things much clearer.

Once again, thanks for clarifying this for me,

Jon

[googleadsapi...@google.com]

Hi Jon,

Sure, I have passed this to our team.

Regards,
Dhanya, Google Ads API Team

=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~
Also find us on our blog and discussion group:
    http://googleadsdeveloper.blogspot.com/search/label/adwords_api
    https://developers.google.com/adwords/api/community/
=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~

Was your question answered? Please rate your experience with us by taking a short survey.
If not -- reply to this email and tell us what else we can do to help.

Take Survey

Also find us on our blog and discussion group:
http://googleadsdeveloper.blogspot.com/search/label/adwords_api
https://developers.google.com/adwords/api/community/