Question(s) about adding UserLists and/or UserInterests via the API

Hunter

unread,

Sep 23, 2015, 10:50:45 AM9/23/15

to AdWords API Forum

I have recently started building out support for audience data in our system, right now I am simply creating CriterionUserList using v201502 of the Perl Adwords API, but I have a couple of questions as a result of this process:

1) It appears that userListName is not being returned when a CriterionUserList is created, I am wondering why this is

I make a request to create two CriterionUserLists with dummy data:

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

   <SOAP-ENV:Header>

      <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <clientCustomerId>3302759889</clientCustomerId>

         <developerToken>REDACTED</developerToken>

         <userAgent>REDACTED</userAgent>

         <validateOnly>false</validateOnly>

         <partialFailure>false</partialFailure>

      </RequestHeader>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <operations>

            <operator>ADD</operator>

            <operand xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24344259004</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <userListId>11443018661</userListId>

                  <userListName>Audience1-AudienceService.t1443018661</userListName>

               </criterion>

               <bidModifier>0.1</bidModifier>

            </operand>

         </operations>

         <operations>

            <operator>ADD</operator>

            <operand xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24344259004</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <userListId>21443018661</userListId>

                  <userListName>Audience2-AudienceService.t1443018661</userListName>

               </criterion>

               <bidModifier>10</bidModifier>

            </operand>

         </operations>

      </mutate>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

the corresponding response only lists userListId and type for each CriterionUserList:

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

   <soap:Header>

      <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <requestId>0005206ac85512910a8148c41c02a7cc</requestId>

         <serviceName>AdGroupCriterionService</serviceName>

         <methodName>mutate</methodName>

         <operations>2</operations>

         <responseTime>245</responseTime>

      </ResponseHeader>

   </soap:Header>

   <soap:Body>

      <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <rval>

            <ListReturnValue.Type>AdGroupCriterionReturnValue</ListReturnValue.Type>

            <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24344213764</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <id>192301809604</id>

                  <type>USER_LIST</type>

                  <Criterion.Type>CriterionUserList</Criterion.Type>

                  <userListId>72150894150</userListId>

               </criterion>

               <AdGroupCriterion.Type>BiddableAdGroupCriterion</AdGroupCriterion.Type>

               <userStatus>ENABLED</userStatus>

               <systemServingStatus>ELIGIBLE</systemServingStatus>

               <approvalStatus>APPROVED</approvalStatus>

               <biddingStrategyConfiguration>

                  <biddingStrategyType>MANUAL_CPC</biddingStrategyType>

                  <biddingStrategySource>CAMPAIGN</biddingStrategySource>

                  <biddingScheme xsi:type="ManualCpcBiddingScheme">

                     <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>

                     <enhancedCpcEnabled>false</enhancedCpcEnabled>

                  </biddingScheme>

                  <bids xsi:type="CpmBid">

                     <Bids.Type>CpmBid</Bids.Type>

                     <bid>

                        <ComparableValue.Type>Money</ComparableValue.Type>

                        <microAmount>10000</microAmount>

                     </bid>

                     <cpmBidSource>ADGROUP</cpmBidSource>

                  </bids>

                  <bids xsi:type="CpcBid">

                     <Bids.Type>CpcBid</Bids.Type>

                     <bid>

                        <ComparableValue.Type>Money</ComparableValue.Type>

                        <microAmount>100000</microAmount>

                     </bid>

                     <cpcBidSource>ADGROUP</cpcBidSource>

                  </bids>

               </biddingStrategyConfiguration>

               <bidModifier>10.0</bidModifier>

            </value>

            <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24344213764</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <id>192301809604</id>

                  <type>USER_LIST</type>

                  <Criterion.Type>CriterionUserList</Criterion.Type>

                  <userListId>72150894150</userListId>

               </criterion>

               <AdGroupCriterion.Type>BiddableAdGroupCriterion</AdGroupCriterion.Type>

               <userStatus>ENABLED</userStatus>

               <systemServingStatus>ELIGIBLE</systemServingStatus>

               <approvalStatus>APPROVED</approvalStatus>

               <biddingStrategyConfiguration>

                  <biddingStrategyType>MANUAL_CPC</biddingStrategyType>

                  <biddingStrategySource>CAMPAIGN</biddingStrategySource>

                  <biddingScheme xsi:type="ManualCpcBiddingScheme">

                     <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>

                     <enhancedCpcEnabled>false</enhancedCpcEnabled>

                  </biddingScheme>

                  <bids xsi:type="CpmBid">

                     <Bids.Type>CpmBid</Bids.Type>

                     <bid>

                        <ComparableValue.Type>Money</ComparableValue.Type>

                        <microAmount>10000</microAmount>

                     </bid>

                     <cpmBidSource>ADGROUP</cpmBidSource>

                  </bids>

                  <bids xsi:type="CpcBid">

                     <Bids.Type>CpcBid</Bids.Type>

                     <bid>

                        <ComparableValue.Type>Money</ComparableValue.Type>

                        <microAmount>100000</microAmount>

                     </bid>

                     <cpcBidSource>ADGROUP</cpcBidSource>

                  </bids>

               </biddingStrategyConfiguration>

               <bidModifier>10.0</bidModifier>

            </value>

         </rval>

      </mutateResponse>

   </soap:Body>

</soap:Envelope>

Thoughts on why userListName is not included in the response?

1a) Why do I need to supply userListId when creating CriterionUserLists via the API, I believe in the UI you just supply a name. When I left that out I got a RequiredError for that field.

2) Is it possible to create a CriterionUserInterest using v201502 of the API? Whenever I tried to make a similar request as above changing the type to USER_INTEREST I received an "Internal API Error".

Josh Radcliff (AdWords API Team)

unread,

Sep 24, 2015, 8:17:10 AM9/24/15

to AdWords API Forum

Hi Hunter,

See below for my answers to your questions.

1) It appears that userListName is not being returned when a CriterionUserList is created, I am wondering why this is

For CriterionUserList, the unique identifier is the userListId, so I wouldn't expect the name to be returned here because that's not part of the key. Where you will get the name is when you add or get the user list via AdwordsUserListService, or issue a AdGroupCriterionService.get and include the UserListName field in your selector.

1a) Why do I need to supply userListId when creating CriterionUserLists via the API, I believe in the UI you just supply a name. When I left that out I got a RequiredError for that field.

Similar to 1) - the unique identifier for a user list is the userListId.

2) Is it possible to create a CriterionUserInterest using v201502 of the API? Whenever I tried to make a similar request as above changing the type to USER_INTEREST I received an "Internal API Error".

When you create the CriterionUserInterest, are you setting its userInterestId to one of the predefined IDs listed in affinity categories and in-market categories? Keep in mind that a CriterionUserInterest is fundamentally different from a CriterionUserList.

CriterionUserInterest - use this to target users based on one of the predefined affinity or in-market categories
CriterionUserList - use this to target users who are in a UserList in your account

Hope that clears things up. Let me know if you still have questions.

Thanks,

Josh, AdWords API Team

Hunter

unread,

Sep 24, 2015, 9:17:11 AM9/24/15

to AdWords API Forum

Thanks, this was really helpful. I was not aware that the userInterestId had to be one of those pre-existing values, should the documentation for CriterionUserInterest list this requirement?

Hunter

unread,

Sep 24, 2015, 11:44:23 AM9/24/15

to AdWords API Forum

I seem to not get the name either when using the AdgroupCriterionService:

Creating a CriterionUserList:

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

   <SOAP-ENV:Header>

      <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <clientCustomerId>3302759889</clientCustomerId>

         <developerToken>REDACTED</developerToken>

         <userAgent>REDACTED</userAgent>

         <validateOnly>false</validateOnly>

         <partialFailure>false</partialFailure>

      </RequestHeader>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <operations>

            <operator>ADD</operator>

            <operand xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24358096204</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <userListId>11443108611</userListId>

                  <userListName>AudienceForSync31443108611</userListName>

                  <userListMembershipStatus>OPEN</userListMembershipStatus>

               </criterion>

               <bidModifier>0.1</bidModifier>

            </operand>

         </operations>

         <operations>

            <operator>ADD</operator>

            <operand xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24358096204</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <userListId>21443108611</userListId>

                  <userListName>AudienceForSync41443108611</userListName>

                  <userListMembershipStatus>OPEN</userListMembershipStatus>

               </criterion>

               <bidModifier>10</bidModifier>

            </operand>

         </operations>

      </mutate>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

MUTATE RESPONSE

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

   <soap:Header>

      <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <requestId>0005207fe82be3180a816c09f2088df7</requestId>

         <serviceName>AdGroupCriterionService</serviceName>

         <methodName>mutate</methodName>

         <operations>2</operations>

         <responseTime>271</responseTime>

      </ResponseHeader>

   </soap:Header>

   <soap:Body>

      <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <rval>

            <ListReturnValue.Type>AdGroupCriterionReturnValue</ListReturnValue.Type>

            <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24358096204</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <id>193415396404</id>

                  <type>USER_LIST</type>

                  <Criterion.Type>CriterionUserList</Criterion.Type>

                  <userListId>11443108611</userListId>

               <bidModifier>0.10000000149011612</bidModifier>

            </value>

            <value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24358096204</adGroupId>

               <criterion xsi:type="CriterionUserList">

                  <id>193415396644</id>

                  <type>USER_LIST</type>

                  <Criterion.Type>CriterionUserList</Criterion.Type>

                  <userListId>21443108611</userListId>

GET REQUEST

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

   <SOAP-ENV:Header>

      <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <clientCustomerId>3302759889</clientCustomerId>

         <developerToken>REDACTED</developerToken>

         <userAgent>REDACTED</userAgent>

         <validateOnly>false</validateOnly>

         <partialFailure>false</partialFailure>

      </RequestHeader>

   </SOAP-ENV:Header>

   <SOAP-ENV:Body>

      <get xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <serviceSelector>

            <fields>Id</fields>

            <fields>AdGroupId</fields>

            <fields>BidModifier</fields>

            <fields>UserListId</fields>

            <fields>UserListName</fields>

            <fields>UserListMembershipStatus</fields>

            <predicates>

               <field>AdGroupId</field>

               <operator>IN</operator>

               <values>24358096204</values>

            </predicates>

            <predicates>

               <field>CriteriaType</field>

               <operator>IN</operator>

               <values>USER_LIST</values>

               <values>USER_INTEREST</values>

            </predicates>

            <paging>

               <startIndex>0</startIndex>

               <numberResults>10000</numberResults>

            </paging>

         </serviceSelector>

      </get>

   </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

GET RESPONSE

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

   <soap:Header>

      <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <requestId>0005207feae31ba80a0de545ba04aa19</requestId>

         <serviceName>AdGroupCriterionService</serviceName>

         <methodName>get</methodName>

         <operations>1</operations>

         <responseTime>178</responseTime>

      </ResponseHeader>

   </soap:Header>

   <soap:Body>

      <getResponse xmlns="https://adwords.google.com/api/adwords/cm/v201502">

         <rval>

            <totalNumEntries>2</totalNumEntries>

            <Page.Type>AdGroupCriterionPage</Page.Type>

            <entries xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24358096204</adGroupId>

               <criterionUse>BIDDABLE</criterionUse>

               <criterion xsi:type="CriterionUserList">

                  <id>193415396404</id>

                  <type>USER_LIST</type>

                  <Criterion.Type>CriterionUserList</Criterion.Type>

                  <userListId>11443108611</userListId>

               </criterion>

               <AdGroupCriterion.Type>BiddableAdGroupCriterion</AdGroupCriterion.Type>

               <bidModifier>0.10000000149011612</bidModifier>

            </entries>

            <entries xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="BiddableAdGroupCriterion">

               <adGroupId>24358096204</adGroupId>

               <criterionUse>BIDDABLE</criterionUse>

               <criterion xsi:type="CriterionUserList">

                  <id>193415396644</id>

                  <type>USER_LIST</type>

                  <Criterion.Type>CriterionUserList</Criterion.Type>

                  <userListId>21443108611</userListId>

               </criterion>

               <AdGroupCriterion.Type>BiddableAdGroupCriterion</AdGroupCriterion.Type>

               <bidModifier>10.0</bidModifier>

            </entries>

         </rval>

      </getResponse>

   </soap:Body>

</soap:Envelope>

On Thursday, September 24, 2015 at 8:17:10 AM UTC-4, Josh Radcliff (AdWords API Team) wrote:

Josh Radcliff (AdWords API Team)

unread,

Sep 24, 2015, 3:58:38 PM9/24/15

to AdWords API Forum

Hi Hunter,

What I mentioned earlier applies here as well. The ID of the CriterionUserList is part of the unique key, but name is not. If you need the name for the user list, please use AdwordsUserListService to retrieve it in a separate call.

Thanks,

Josh, AdWords API Team

...

Hunter

unread,

Sep 24, 2015, 4:00:20 PM9/24/15

to AdWords API Forum

I was referring to this statement that you made above: "or issue a AdGroupCriterionService.get and include the UserListName field in your selector."

Josh Radcliff (AdWords API Team)

unread,

Sep 24, 2015, 5:28:04 PM9/24/15

to AdWords API Forum

Hi Hunter,

Sorry -- my mistake. I misread the SOAP response and thought it was from a mutate call. Indeed, it seems we have an issue here, as I can't get the user list name back from AdGroupCriterionService either. I've reported this issue and will get back to you as soon as I have an update.