Video: Check out the Listing Groups talk from the 2019 workshop
Hotel ad groups support partitioning your hotels into many hotel listing groups, across multiple dimensions so you can adjust bids for each group accordingly. Consider the tree below, where at the first level, the hotels have been broadly divided as 5-star hotels, 4-star hotels, and other hotel classes. At the second level, the hotels in other hotel classes have been divided as "United States" hotels, "United Kingdom" hotels, and hotels in other regions.
Each node in the tree is either a subdivision or a unit, as defined by ListingGroupType
.
A subdivision introduces a
new level in the tree, while units are leaves of the tree. Each subdivision must
always be completely partitioned, so it must contain a node representing Other. In the example, the root and Hotel Class: (Other)nodes are
subdivisions. This tree structure with subdivisions and units lets you set
bids at the unit level and also ensures that every hotel listing falls into one
and only one unit node in the tree.
Nodes are objects of the ListingGroupInfo
class,
which contains the ListingGroupType
field that
indicates if the nodes are unit or subdivision. Setting ListingGroupInfo
to listing_group
of AdGroupCriterion
will link it to
the AdGroup
.
Setting Percent CPC bids
You are allowed to set percent_cpc_bid_micros
of AdGroupCriterion
on only unit nodes. Attempting to
do so on subdivision nodes will fail with an error.
Listing dimensions
A ListingGroupInfo
also has a case_value
which is
a ListingDimensionInfo
that contains one of
several dimension type. A ListingGroupInfo
represents the values associated
with your hotels, such as hotel ID, hotel country, or hotel class. A full description of
the available ListingDimensionInfo
types is available in the reference
documentation
.
Each immediate child of a subdivision must have a case_value
of the same ListingDimensionInfo
subtype. Only the root node doesn't have a case_value
.
Remember that each subdivision must contain an "empty" case_value
of the
correct type, representing "all other values".
For more details, check out the following code snippet which adds the first level of the listing group tree.
Java
private static String addLevel1Nodes ( long customerId , long adGroupId , String rootResourceName , List<AdGroupCriterionOperation> operations , long percentCpcBidMicroAmount ) { // Creates hotel class info and dimension info for 5-star hotels. ListingDimensionInfo fiveStarredDimensionInfo = ListingDimensionInfo . newBuilder () . setHotelClass ( HotelClassInfo . newBuilder (). setValue ( 5 ). build ()) . build (); // Creates listing group info for 5-star hotels as a UNIT node. ListingGroupInfo fiveStarredUnit = ListingGroupInfo . newBuilder () . setType ( ListingGroupType . UNIT ) . setParentAdGroupCriterion ( rootResourceName ) . setCaseValue ( fiveStarredDimensionInfo ) . build (); // Creates an ad group criterion for 5-star hotels. AdGroupCriterion fiveStarredAdGroupCriterion = createAdGroupCriterion ( customerId , adGroupId , fiveStarredUnit , percentCpcBidMicroAmount ); // Decrements the temp ID for the next ad group criterion. AdGroupCriterionOperation operation = generateCreateOperation ( fiveStarredAdGroupCriterion ); operations . add ( operation ); // You can also create more UNIT nodes for other hotel classes by copying the above code in // this method and modifying the value passed to HotelClassInfo() to the value you want. // For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star // hotels instead. // Creates hotel class info and dimension info for other hotel classes by not specifying // any attributes on those object. ListingDimensionInfo otherHotelsDimensionInfo = ListingDimensionInfo . newBuilder () . setHotelClass ( HotelClassInfo . newBuilder (). build ()) . build (); // Creates listing group info for other hotel classes as a SUBDIVISION node, which will be // used as a parent node for children nodes of the next level. ListingGroupInfo otherHotelsSubdivision = createListingGroupInfo ( ListingGroupType . SUBDIVISION , rootResourceName , otherHotelsDimensionInfo ); // Creates an ad group criterion for other hotel classes. AdGroupCriterion otherHotelsAdGroupCriterion = createAdGroupCriterion ( customerId , adGroupId , otherHotelsSubdivision , percentCpcBidMicroAmount ); operation = generateCreateOperation ( otherHotelsAdGroupCriterion ); operations . add ( operation ); return otherHotelsAdGroupCriterion . getResourceName (); }
C#
private string AddLevel1Nodes ( long customerId , long adGroupId , string rootResourceName , List<AdGroupCriterionOperation> operations , long percentCpcBidMicroAmount ) { // Create listing dimension info for 5-star class hotels. ListingDimensionInfo fiveStarredListingDimensionInfo = new ListingDimensionInfo { HotelClass = new HotelClassInfo { Value = 5 } }; // Create a listing group info for 5-star hotels as a UNIT node. ListingGroupInfo fiveStarredUnit = CreateListingGroupInfo ( ListingGroupType . Unit , rootResourceName , fiveStarredListingDimensionInfo ); // Create an ad group criterion for 5-star hotels. AdGroupCriterion fiveStarredAdGroupCriterion = CreateAdGroupCriterion ( customerId , adGroupId , fiveStarredUnit , percentCpcBidMicroAmount ); // Create an operation and add it to the list of operations. operations . Add ( new AdGroupCriterionOperation { Create = fiveStarredAdGroupCriterion }); // Decrement the temp ID for the next ad group criterion. nextTempId -- ; // You can also create more UNIT nodes for other hotel classes by copying the above code // in this method and modifying the value passed to HotelClassInfo(). // For instance, passing 4 instead of 5 in the above code will instead create a UNIT // node of 4-star hotels. // Create hotel class info and dimension info for other hotel classes by *not* // specifying any attributes on those object. ListingDimensionInfo otherHotelsListingDimensionInfo = new ListingDimensionInfo { HotelClass = new HotelClassInfo () }; // Create listing group info for other hotel classes as a SUBDIVISION node, which will // be used as a parent node for children nodes of the next level. ListingGroupInfo otherHotelsSubdivisionListingGroupInfo = CreateListingGroupInfo ( ListingGroupType . Subdivision , rootResourceName , otherHotelsListingDimensionInfo ); // Create an ad group criterion for other hotel classes. AdGroupCriterion otherHotelsAdGroupCriterion = CreateAdGroupCriterion ( customerId , adGroupId , otherHotelsSubdivisionListingGroupInfo , percentCpcBidMicroAmount ); // Create an operation and add it to the list of operations. operations . Add ( new AdGroupCriterionOperation { Create = otherHotelsAdGroupCriterion }); // Decrement the temp ID for the next ad group criterion. nextTempId -- ; return otherHotelsAdGroupCriterion . ResourceName ; }
PHP
private static function addLevel1Nodes( int $customerId, int $adGroupId, string $rootResourceName, array &$operations, int $percentCpcBidMicroAmount ) { // Creates hotel class info and dimension info for 5-star hotels. $fiveStarredDimensionInfo = new ListingDimensionInfo([ 'hotel_class' => new HotelClassInfo(['value' => 5]) ]); // Creates listing group info for 5-star hotels as a UNIT node. $fiveStarredUnit = self::createListingGroupInfo( ListingGroupType::UNIT, $rootResourceName, $fiveStarredDimensionInfo ); // Creates an ad group criterion for 5-star hotels. $fiveStarredAdGroupCriterion = self::createAdGroupCriterion( $customerId, $adGroupId, $fiveStarredUnit, $percentCpcBidMicroAmount ); // Decrements the temp ID for the next ad group criterion. self::$nextTempId--; $operation = self::generateCreateOperation($fiveStarredAdGroupCriterion); $operations[] = $operation; // You can also create more UNIT nodes for other hotel classes by copying the above code in // this method and modifying the value passed to HotelClassInfo() to the value you want. // For instance, passing 4 instead of 5 in the above code will create a UNIT node of 4-star // hotels instead. // Creates hotel class info and dimension info for other hotel classes by *not* specifying // any attributes on those object. $othersHotelsDimensionInfo = new ListingDimensionInfo([ 'hotel_class' => new HotelClassInfo() ]); // Creates listing group info for other hotel classes as a SUBDIVISION node, which will be // used as a parent node for children nodes of the next level. $otherHotelsSubDivision = self::createListingGroupInfo( ListingGroupType::SUBDIVISION, $rootResourceName, $othersHotelsDimensionInfo ); // Creates an ad group criterion for other hotel classes. $otherHotelsAdGroupCriterion = self::createAdGroupCriterion( $customerId, $adGroupId, $otherHotelsSubDivision, $percentCpcBidMicroAmount ); $operation = self::generateCreateOperation($otherHotelsAdGroupCriterion); $operations[] = $operation; self::$nextTempId--; return $otherHotelsAdGroupCriterion->getResourceName(); }
