Regions

The regions service allows you to create and manage geographic regions that you can use as targets with both the regionalinventory and shippingsettings services. You can define regions as collections of either postal codes or, in some countries, using predefined geotargets. This guide provides examples of how to define each type of region, as well how to create a regional pricing override. For additional information about the regions service, including all available methods and parameters, see the reference documentation.

Region eligibility

When you create a region, the regions service determines whether you can use the region with other Content API services. The response object returned for a successful regions.create call includes two boolean fields, regionalInventoryEligible and shippingEligible, which indicate whether you can use the region with the regionalinventory and shippingsettings services, respectively.

regionalInventoryEligible

To be eligible for use with the regionalinventory service, a region must meet the following criteria:

  • The regionId, which you specify when creating a region, must contain only digits and must contain at least 6 digits.
  • The region must meet minimum size requirements for geographic area and online population.

shippingEligible

To be eligible for use with the shippingsettings service, a region must meet the following criteria:

  • The region must be defined using postal codes.
  • The region must be part of a country supported by the shippingsettings service.

Samples

Here's a full code sample you can use to create a new region in Java:

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package shopping.content.v2_1.samples.regions;

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.services.content.model.Region;
import com.google.api.services.content.model.RegionPostalCodeArea;
import com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import shopping.content.v2_1.samples.ContentSample;

/**
 * Creates a region. The region created here can be used with the regional inventory service.
 * Regional availability and pricing lets you provide product availability and variable pricing
 * based on your business presence and the location of your customer base. Regional availability and
 * pricing is available for products advertised through Shopping ads on Google Search, and listed in
 * free listings on the Shopping tab.
 */
public class RegionCreateSample extends ContentSample {
  public RegionCreateSample(String[] args) throws IOException {
    super(args);
  }

  @Override
  public void execute() throws IOException {
    checkNonMCA();

    // Creates a List of Postal Code Area Postal Code Ranges.
    // This allows you to flexibly define regions as combinations of postal code
    // ranges. Each postal code range in the list has its own start and end zip code.
    List<RegionPostalCodeAreaPostalCodeRange> postalCodeRanges =
        new ArrayList<RegionPostalCodeAreaPostalCodeRange>();

    // Creates a new postal code range from two postal code values.
    // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925)
    RegionPostalCodeAreaPostalCodeRange postalCodeRange =
        new RegionPostalCodeAreaPostalCodeRange().setBegin("00501").setEnd("14925");

    // Adds the NY State postal code range into the list of postal code ranges that a postal
    // code area accepts.
    postalCodeRanges.add(postalCodeRange);

    // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code
    // ranges, and the US CLDR territory/country code that the postal code ranges applies to.
    RegionPostalCodeArea postalCodeArea =
        new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode("US");

    // Creates a region with example values for displayName and postalCodeArea
    Region region = new Region().setDisplayName("NYState").setPostalCodeArea(postalCodeArea);

    // Tries to create the region, and catches any exceptions
    try {
      System.out.println("Creating region");
      Region result =
          content
              .regions()
              .create(this.config.getMerchantId().longValue(), region)
              .setRegionId("12345678") // User-defined, numeric, minimum of 6 digits
              .execute();
      System.out.println("Listing succesfully created region");
      System.out.println(result);
    } catch (GoogleJsonResponseException e) {
      checkGoogleJsonResponseException(e);
    }
  }

  public static void main(String[] args) throws IOException {
    new RegionCreateSample(args).execute();
  }
}

Create a region using postal codes

You can use the regions.create method to create a region defined as a collection of postal codes. The example below creates a new region for the US state of Arizona by specifying a range of postal codes.

To create the region, make a POST request with the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodeArea: {
    regionCode: "US",
    postalCodes: [
      {
        begin: "850*",
        end: "860*"
      }
    ]
   }
}

There is a hard limit of 2MB of data for regions and shippingsettings per Merchant Center account. Shipping and region settings are internally copied from an MCA to all of its subaccounts, so for larger MCAs, you might quickly reach your storage limit. In this case, a workaround is to manage regions and shippingsettings at the merchant ID level. There is no way to increase your regions quota past the 2MB limit.

Create a region using geotargets

For regions in Brazil and Russia, you can also use the regions.create method to create a region defined as a collection of geotargets, which are predefined geographic areas. Examples of geotarget types include countries, states, cities, neighborhoods, and airports. However, the regions service currently only supports the “State” type for Brazil and the “Region” type for Russia. To download a csv file of all geotarget IDs, including the geotargets that can be used with the regions service, see Geotargets. The example below creates a new region by providing the geotarget IDs of three Brazilian states.

To create the region, make a POST request using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456

{
  geoTargetAreas: {
    geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
  }
}

Use regions to create regional price overrides

When you create a region, the regions service returns an response object that includes a regionId and two eligibility status fields. If the regionalInventoryEligible value is true, you can use the regionaliventory service to create an override that sets a different price for the region. The example below creates a regional price override using the postal-code-based region created in the example above, which has a regionId of “456789”.

To create the override, make a POST request using the following URL and request body:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory

{
  “regionId”: "456789"
  “price”: {
    value: “10”
    currency: “USD”
  },
  “availability”: “in stock”
}