Differences between similar fields in UserList and CriterionUserList entities

[adiv...@wordstream.com]

Hello AdWords API Team,

I have a question regarding the function of a couple of fields that are being introduced for the CampaignCriterionService.CriterionUserList and AdGroupCriterionUserList.CriterionUserList types in v201603 of the AdWords API.

The new fields are:

• CampaignCriterionService.CriterionUserList.userListEligibleForSearch
  
• CampaignCriterionService.CriterionUserList.userListEligibleForDisplay
  
• AdGroupCriterionService.CriterionUserList.userListEligibleForSearch
  
• AdGroupCriterionService.CriterionUserList.userListEligibleForDisplay
  

Each instance of a CampaignCriterionService.CriterionUserList and AdGroupCriterionService.CriterionUserList specifies a userListId field - which references a AdwordsUserListService.UserList.id value in the account and, therefore, identifies the UserList entity that the CriterionUserList that has been linked to the AdGroup or Campaign.

Now my question arises from the fact that the UserList entity, itself, defines the following two fields:

• UserList.isEligibleForSearch
  
• UserList.isEligibleForDisplay
  

Those two UserList above and the four CriterionUserList fields mentioned earlier look very similar.  Can you explain what the difference in purpose is between the UserList and CriterionUserList fields?  I'm unclear as tp why the four CriterionUserList fields exist separately from the two UserList fields.  

For example, under what circumstances would a value of CampaignCriterionService.CriterionUserList.userListEligibleForSearch be set to a different value than the value of the UserList.isEligibleForSearch field on the corresponding UserList entity whose id value matches the CriterionUserList.userListId value?

Many thanks!

-Al

[Joyce Lava]

Hi Al,

Please see below differences for each field in each service:

CampaignCriterionService.CriterionUserList.userListEligibleForSearch - is used to manage campaign-level criteria. This is used when the campaign targets a group of people who visited the campaign on Google Search. You need to set the CampaignCriterion with criterion as CriterionUserList. CampaignCriterionService.CriterionUserList.userListEligibleForDisplay on the other hand is used to target people who visited the website on Google Display Network.

AdGroupCriterionService.CriterionUserList.userListEligibleForSearch - is used to manage criteria such as keywords or placements. This is used when the keyword bids for people who recently visited the website on Google Search. You need to set BiddableAdGroupCriterion with criterion as CriterionUserList. AdGroupCriterionService.CriterionUserList.userListEligibleForDisplay on the other hand is used to target people who visit Google Display Network.

UserList.isEligibleForSearch - is used to manage the user lists. This is the list of users that an account may target. With the list of users that has been created using the AdWordsUserListService, you may then use this user list to target on the campaign level(CampaignCriterionService.CriterionUserList) or on keywords or placements(AdGroupCriterionService.CriterionUserList).

With the explanation above on the differences, what I am aware of is you should only use the CriterionUserList.userListEligibleForSearch and CriterionUserList.userListEligibleForDisplay for validation as they are read-only fields in the CampaignCriterionService and AdGroupCriterionService.

Hope it helps.

Thanks and Regards,

Joyce, AdWords API Team

[adiv...@wordstream.com]

Hello Joyce,

Thank you for your  detailed response.  The explanations you provide are very clear and make sense, but they do not quite fully answer my inquiry.

I probably did not phrase my inquiry in the most direct way in my initial posting, so let me try another way of posing the question.

a) Let's say I have created an instance of an AdwordsUserListService.UserList and it has an id field value of 1234 and an isEligibleForSearch field value of "true".

b) Let's say that I have an instance of an AdGroupCriterionService.AdGroupCriterion entity whose criterion field is  an instance of CriterionUserList

c) Let's say that the particular CriterionUserList set for the "criterion" has a userListId value of 1234 that references the AdwordsUserListService.UserList instance from "a".

So now my question becomes...

Would the userListEligibleForSearch value for the criterion described in "c" be determined by the value of the isEligibleForSearch field for the referenced UserList?  If not, what factors would determine the value of the userListEligibleForSearch value of this criterion - keeping in mind that the value of the userListEligibleForSearch field is not, itself, settable via the AdWords API?

Thanks again!

-Al

[Joyce Lava]

Hi Al,

To answer your question above, what I am aware of is, userListEligibleForSearch in CriterionUserList is read only based on the documentation. With that said, the value should be from AdwordsUserListService.UserList.isEligibleForSearch. 

However, I tried creating a CrmBasedUserList using the AdwordsUserListService and sent the "isEligibleForSearch" as false but it seems that the field value is ignored. Let me check with my teammates more about AdwordsUserListService.UserList.isEligibleForSearch. 

[Joyce Lava]

Hi Al,

I have confirmed that AdGroupCriterionService.CriterionUserList.UserListEligibleForSearch field is read only. When CriterionUserList refers to any AdwordsUserListService.UserList, then the AdGroupCriterionService.CriterionUserList.UserListEligibleForSearch field value is determined by the AdwordsUserListService.UserList.isEligibleForSearch. 

[adiv...@wordstream.com]

Hello Joyce,

Thank you so much for following up with your team to provide an answer to my question.

I have a few related questions below.

1) Does a similar relationship exist between the value of a CampaignCriterionService.CriterionUserList.userListEligibleForSearch field and the value of a UserList.isEligibleForSearch field for an instance of a UserList whose id field is referenced by the userListId field of the CampaignCriterionService.CriterionUserList instance?

2) Does  similar relationship exist between the value of an CampaignCriterionService.CriterionUserList.userListEligibleForDisplay field and the value of a UserList.isEligibleForDisplay field for an instance of a UserList whose id field is referenced by the userListId field of the CampaignCriterionService.CriterionUserList instance?

3) Does  similar relationship exist between the value of an AdGroupCriterionService.CriterionUserList.userListEligibleForDisplay field and the value of a UserList.isEligibleForDisplay field for an instance of a UserList whose id field is referenced by the userListId field of the AdGroupCriterionService.CriterionUserList instance?

I suspect the answer to all of the above is "yes", but it never hurts to be sure! :-)

Thanks again,

-Al

[Joyce Lava]

Hi Al,

Yes, you are correct. The explanation provided in the previous post applies with the userListEligibleForDisplay and userListEligibleForSearch fields of CampaignCriterionService and AdGroupCriterionService as well referenced to AdwordsUserListService.UserList.

[adiv...@wordstream.com]

Hello Joyce,

Is the AdwordsUserListService.UserList.isEligibleForSearch a read-only field?  I re-read your response in here and I just noticed that this response addresses the AdGroupCriterionService.CriterionUserList.UserListEligibleForSearch field, but not the AdwordsUserListService.UserList.isEligibleForSearch field that I had originally asked about.

Sorry for not noticing that earlier and thanks in advance!

-Al

[Joyce Lava]

Hi Al,

I apologize for the misunderstanding. In the original posts you were asking if AdwordsUserListService.UserList.isEligibleForSearch determines the value of the AdGroupCriterionService.CriterionUserList.UserListEligibleForSearch. And with this context, I answered the previous posts. Informed that yes, the value of AdGroupCriterionService.CriterionUserList.UserListEligibleForSearch will be determined by AdwordsUserListService.UserList.isEligibleForSearch because the field UserListEligibleForSearch in the CriterionUserList is read-only, meaning, if you include this in the request of the AdGroupCriterionService, the field UserListEligibleForSearch will be ignored by the API.

And to answer your concern now regarding AdwordsUserListService.UserList.isEligibleForSearch if it is read-only, no, the field isEligibleForSearch is not read-only when you include it in the request of AdwordsUserListService.

I hope it clears all the confusion.

Best Regards,

Joyce, AdWords API Team