Google Ads API is returning to beta status. Please read our blog post for more details.

Creating Shopping Listing Groups

Shopping listing groups allow you to partition your products into groups (referred to as product groups in the UI). You can group using multiple dimensions, allowing you to set bids or exclude products. Consider the tree below, where at the first level, the products have been divided by condition into New, Used and other product conditions. At the second level, the products in other product conditions have been divided by brand as "CoolBrand" products, "CheapBrand", and other brands.

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 Product Condition: (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 product 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 Manual CPC bids

You are allowed to set 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 products, such as offer ID, brand, or product condition. A full description of the available ListingDimensionInfo types is available in the reference documentation.

Each 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. This child is usually referred to as Other because it represents "all other values" for that ListingDimensionInfo.

See the code snippets below that add the first level of the listing group tree for more detail.

Java
private void runExample(
    GoogleAdsClient googleAdsClient,
    long customerId,
    long adGroupId,
    boolean replaceExistingTree) {
  // 1) Optional: Removes the existing listing group tree, if it already exists on the ad group.
  if (replaceExistingTree) {
    removeListingGroupTree(googleAdsClient, customerId, adGroupId);
  }
  // Creates a list of ad group criterion to add.q
  List<AdGroupCriterionOperation> operations = new ArrayList<>();

  // 2) Constructs the listing group tree "root" node.

  // Subdivision node: (Root node)
  AdGroupCriterion adGroupCriterionRoot =
      createListingGroupSubdivisionRoot(customerId, adGroupId, -1L);
  // Get the resource name that will be used for the root node.
  // This resource has not been created yet and will include the temporary ID as part of the
  // criterion ID.
  String adGroupCriterionResourceNameRoot = adGroupCriterionRoot.getResourceName();
  operations.add(AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionRoot).build());

  // 3) Construct the listing group unit nodes for NEW, USED and other

  // Biddable Unit node: (Condition NEW node)
  // * Product Condition: NEW
  // * CPC bid: $0.20
  AdGroupCriterion adGroupCriterionConditionNew =
      createListingGroupUnitBiddable(
          customerId,
          adGroupId,
          adGroupCriterionResourceNameRoot,
          ListingDimensionInfo.newBuilder()
              .setProductCondition(
                  ProductConditionInfo.newBuilder().setCondition(ProductCondition.NEW).build())
              .build(),
          200_000L);
  operations.add(
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionConditionNew).build());

  // Biddable Unit node: (Condition USED node)
  // * Product Condition: USED
  // * CPC bid: $0.10
  AdGroupCriterion adGroupCriterionConditionUsed =
      createListingGroupUnitBiddable(
          customerId,
          adGroupId,
          adGroupCriterionResourceNameRoot,
          ListingDimensionInfo.newBuilder()
              .setProductCondition(
                  ProductConditionInfo.newBuilder().setCondition(ProductCondition.USED).build())
              .build(),
          100_000L);
  operations.add(
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionConditionUsed).build());

  // Sub-division node: (Condition "other" node)
  // * Product Condition: (not specified)
  AdGroupCriterion adGroupCriterionConditionOther =
      createListingGroupSubdivision(
          customerId,
          adGroupId,
          -2L,
          adGroupCriterionResourceNameRoot,
          ListingDimensionInfo.newBuilder()
              // All sibling nodes must have the same dimension type, even if they don't contain a
              // bid.
              // parent
              .setProductCondition(ProductConditionInfo.newBuilder().build())
              .build());
  // Gets the resource name that will be used for the condition other node.
  // This resource has not been created yet and will include the temporary ID as part of the
  // criterion ID.
  String adGroupCriterionResourceNameConditionOther =
      adGroupCriterionConditionOther.getResourceName();
  operations.add(
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionConditionOther).build());

  // 4) Constructs the listing group unit nodes for CoolBrand, CheapBrand and other

  // Biddable Unit node: (Brand CoolBrand node)
  // * Brand: CoolBrand
  // * CPC bid: $0.90
  AdGroupCriterion adGroupCriterionBrandCoolBrand =
      createListingGroupUnitBiddable(
          customerId,
          adGroupId,
          adGroupCriterionResourceNameConditionOther,
          ListingDimensionInfo.newBuilder()
              .setListingBrand(
                  ListingBrandInfo.newBuilder().setValue(StringValue.of("CoolBrand")).build())
              .build(),
          900_000L);
  operations.add(
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionBrandCoolBrand).build());

  // Biddable Unit node: (Brand CheapBrand node)
  // * Brand: CheapBrand
  // * CPC bid: $0.01
  AdGroupCriterion adGroupCriterionBrandCheapBrand =
      createListingGroupUnitBiddable(
          customerId,
          adGroupId,
          adGroupCriterionResourceNameConditionOther,
          ListingDimensionInfo.newBuilder()
              .setListingBrand(
                  ListingBrandInfo.newBuilder().setValue(StringValue.of("CheapBrand")).build())
              .build(),
          10_000L);
  operations.add(
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionBrandCheapBrand).build());

  // Biddable Unit node: (Brand other node)
  // * Brand: CheapBrand
  // * CPC bid: $0.01
  AdGroupCriterion adGroupCriterionBrandOther =
      createListingGroupUnitBiddable(
          customerId,
          adGroupId,
          adGroupCriterionResourceNameConditionOther,
          ListingDimensionInfo.newBuilder()
              .setListingBrand(ListingBrandInfo.newBuilder().build())
              .build(),
          50_000L);
  operations.add(
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterionBrandOther).build());

  // Issues a mutate request to add the ad group criterion to the ad group.
  try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
    List<MutateAdGroupCriterionResult> mutateAdGroupCriteriaResults =
        adGroupCriterionServiceClient
            .mutateAdGroupCriteria(Long.toString(customerId), operations)
            .getResultsList();
    for (MutateAdGroupCriterionResult mutateAdGroupCriterionResult :
        mutateAdGroupCriteriaResults) {
      System.out.printf(
          "Added ad group criterion for listing group with resource name: '%s'%n",
          mutateAdGroupCriterionResult.getResourceName());
    }
  }
}

Available dimensions for ListingDimensionInfo

There are multiple listing dimensions that can be part of a listing group (at an ad group level) or a listing scope (at a campaign level).

The following ListingDimensionInfo types can be used with shopping campaigns:

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 and an Other node in the same request.

To allow you to set the parent_criterion_id of ListingGroupInfo for the child nodes created in the same request of the parent, 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.

Code examples

You can explore the code examples in each language by following the links below:

Languages File names
Java AddShoppingProductListingGroupTree.java

傳送您對下列選項的寶貴意見...

這個網頁
Google Ads API Beta
Google Ads API Beta
需要協助嗎?請前往我們的支援網頁