Creating Hotel Listing Groups

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 allows you to 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.

Key Point: You need at least one unit node in order to make a tree valid. Hotel Ads will not serve until you create a valid listing group tree.

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.

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' => new Int64Value(['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();
}
AddHotelListingGroupTree.php

Available dimensions for ListingDimensionInfo

The following ListingDimensionInfo types are available for Hotel Ads:

• HotelIdInfo
• HotelClassInfo
• HotelCountryRegionInfo
• HotelStateInfo
• HotelCityInfo

Tip: Others unit nodes can be created by passing an empty object of ListingDimensionInfo types to ListingGroupInfo. You also have to set the percent_cpc_bid_micros field of the AdGroupCriterion of an Others unit node.

Temporary IDs

Ad group criteria are not assigned IDs until the mutate request that creates them is processed by the server. However, a ListingGroupInfo is invalid until it is complete, so whenever you create a subdivision you must also create at least one of its children in the same operation.

To allow you to set the parent_criterion_id of ListingGroupInfo for the child nodes, you can use temporary criterion IDs. These are locally unique (rather than globally unique) identifiers that apply only within the context of a single mutate request. Any negative integer can be used as a temporary ID. In the code examples, the ID of the root ListingGroupInfo is set to -1.

When the request is processed, each AdGroupCriterion is assigned a positive global ID as usual.