借助 regions 服务,您可以创建和管理地理区域,并将其用作 regionalinventory 和 shippingsettings 服务的定位条件。您可以将区域定义为邮政编码的集合,也可以在某些国家/地区使用预定义的地理位置定位目标。本指南提供了有关如何定义每种类型的地区以及如何创建地区性价格替换的示例。如需详细了解 regions 服务(包括所有可用的方法和参数),请参阅参考文档。
每个 Merchant Center 账号的 regions 和 shippingsettings 数据量硬性限制为 2 MB。配送和区域设置会从 MCA 内部复制到其所有子账号,因此对于较大的 MCA,您可能会很快达到存储空间上限。在这种情况下,一种解决方法是在商家 ID 级别管理 regions 和 shippingsettings。无法将区域配额增加到 2MB 上限以上。
使用地理位置定位条件创建地区
对于巴西和俄罗斯的地区,您还可以使用 regions.create 方法来创建定义为地理定位目标集合的地区,这些地理定位目标是预定义的地理区域。地理位置定位类型包括国家/地区、州/省/自治区/直辖市、城市、社区和机场。不过,regions 服务目前仅支持巴西的“州”类型和俄罗斯的“地区”类型。如需下载包含所有地理定位 ID(包括可与 regions 服务搭配使用的地理定位)的 CSV 文件,请参阅地理定位。以下示例通过提供三个巴西州的地理定位 ID 来创建新区域。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[[["\u003cp\u003eThe Merchant API is the new version of the Content API for Shopping and allows you to create and manage geographic regions.\u003c/p\u003e\n"],["\u003cp\u003eRegions can be defined using postal codes or geotargets (in Brazil and Russia), and their eligibility for use with regional inventory and shipping settings is determined by specific criteria.\u003c/p\u003e\n"],["\u003cp\u003eYou can use the \u003ccode\u003eregions.create\u003c/code\u003e method to create regions and the \u003ccode\u003eregionalinventory\u003c/code\u003e service to create regional price overrides.\u003c/p\u003e\n"],["\u003cp\u003eThere is a 2MB storage limit for regions and shipping settings per Merchant Center account, and managing these at the merchant ID level is a workaround for larger accounts.\u003c/p\u003e\n"]]],["The Merchant API beta introduces the `regions` service, allowing users to define geographic regions for targeting with `regionalinventory` and `shippingsettings` services. Regions are defined using postal codes or, in specific countries, geotargets (e.g., states in Brazil, regions in Russia). Creating a region involves specifying a `regionId` (numeric, at least six digits) and defining its area, which can include postal code ranges or geotarget IDs. Eligibility fields determine whether a region can be used with the aforementioned services, based on requirements such as the number of digits in the region ID, region size, if it is defined using postal code, and supported countries. The `regionalinventory` service allows for creating regional price overrides based on these defined regions.\n"],null,["# Regions\n\nThe `regions` service allows you to create and manage geographic regions that\nyou can use as targets with both the\n[`regionalinventory`](/shopping-content/reference/rest/v2.1/regionalinventory)\nand [`shippingsettings`](/shopping-content/reference/rest/v2.1/shippingsettings)\nservices. You can define regions as collections of either postal codes or, in\nsome countries, using predefined\n[geotargets](/google-ads/api/reference/data/geotargets). This guide provides\nexamples of how to define each type of region, as well how to create a regional\npricing override. For additional information about the `regions` service,\nincluding all available methods and parameters, see the reference documentation.\n| **Note:** Each region definition can contain only postal codes or geotargets---not both.\n\nRegion eligibility\n------------------\n\nWhen you create a region, the regions service determines whether you can use the\nregion with other Content API services. The response object returned for a\nsuccessful `regions.create` call includes two boolean fields,\n`regionalInventoryEligible` and `shippingEligible`, which indicate whether you\ncan use the region with the `regionalinventory` and `shippingsettings` services,\nrespectively.\n\n### regionalInventoryEligible\n\nTo be eligible for use with the `regionalinventory` service, a region must meet\nthe following criteria:\n\n- The `regionId`, which you specify when creating a region, must contain only digits and must contain at least 6 digits.\n- The region must meet minimum size requirements for geographic area and online population.\n\n### shippingEligible\n\nTo be eligible for use with the `shippingsettings` service, a region must meet\nthe following criteria:\n\n- The region must be defined using postal codes.\n- The region must be part of a country supported by the `shippingsettings` service.\n\nSamples\n-------\n\nHere's a full code sample you can use to create a new region in Java: \n\n```python\n// Copyright 2023 Google LLC\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\npackage shopping.content.v2_1.samples.regions;\n\nimport com.google.api.client.googleapis.json.GoogleJsonResponseException;\nimport com.google.api.services.content.model.Region;\nimport com.google.api.services.content.model.RegionPostalCodeArea;\nimport com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange;\nimport java.io.IOException;\nimport java.util.ArrayList;\nimport java.util.List;\nimport shopping.content.v2_1.samples.ContentSample;\n\n/**\n * Creates a region. The region created here can be used with the regional inventory service.\n * Regional availability and pricing lets you provide product availability and variable pricing\n * based on your business presence and the location of your customer base. Regional availability and\n * pricing is available for products advertised through Shopping ads on Google Search, and listed in\n * free listings on the Shopping tab.\n */\npublic class RegionCreateSample extends ContentSample {\n public RegionCreateSample(String[] args) throws IOException {\n super(args);\n }\n\n @Override\n public void execute() throws IOException {\n checkNonMCA();\n\n // Creates a List of Postal Code Area Postal Code Ranges.\n // This allows you to flexibly define regions as combinations of postal code\n // ranges. Each postal code range in the list has its own start and end zip code.\n List\u003cRegionPostalCodeAreaPostalCodeRange\u003e postalCodeRanges =\n new ArrayList\u003cRegionPostalCodeAreaPostalCodeRange\u003e();\n\n // Creates a new postal code range from two postal code values.\n // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925)\n RegionPostalCodeAreaPostalCodeRange postalCodeRange =\n new RegionPostalCodeAreaPostalCodeRange().setBegin(\"00501\").setEnd(\"14925\");\n\n // Adds the NY State postal code range into the list of postal code ranges that a postal\n // code area accepts.\n postalCodeRanges.add(postalCodeRange);\n\n // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code\n // ranges, and the US CLDR territory/country code that the postal code ranges applies to.\n RegionPostalCodeArea postalCodeArea =\n new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode(\"US\");\n\n // Creates a region with example values for displayName and postalCodeArea\n Region region = new Region().setDisplayName(\"NYState\").setPostalCodeArea(postalCodeArea);\n\n // Tries to create the region, and catches any exceptions\n try {\n System.out.println(\"Creating region\");\n Region result =\n content\n .regions()\n .create(this.config.getMerchantId().longValue(), region)\n .setRegionId(\"12345678\") // User-defined, numeric, minimum of 6 digits\n .execute();\n System.out.println(\"Listing succesfully created region\");\n System.out.println(result);\n } catch (GoogleJsonResponseException e) {\n checkGoogleJsonResponseException(e);\n }\n }\n\n public static void main(String[] args) throws IOException {\n new RegionCreateSample(args).execute();\n }\n}\n```\n\n### Create a region using postal codes\n\nYou can use the [`regions.create`](/shopping-content/reference/rest/v2.1/regions/create)\nmethod to create a region defined as a collection of postal codes. The example\nbelow creates a new region for the US state of Arizona by specifying a range of\npostal codes.\n\nTo create the region, make a `POST` request with the following URL and request\nbody: \n\n https://shoppingcontent.googleapis.com/content/v2.1/\u003cvar translate=\"no\"\u003emerchantId\u003c/var\u003e/regions?regionId=456789\n\n {\n postalCodeArea: {\n regionCode: \"US\",\n postalCodes: [\n {\n begin: \"850*\",\n end: \"860*\"\n }\n ]\n }\n }\n\n| **Note:** If you get the error \"quota/too_many_regions\", you have run out of storage in your account for regions.\n\nThere is a hard limit of 2MB of data for `regions`\nand `shippingsettings` per Merchant Center account. Shipping and region settings\nare internally copied from an MCA to all of its subaccounts, so for larger\nMCAs, you might quickly reach your storage limit. In this case, a workaround is\nto manage `regions` and `shippingsettings` at the merchant ID level. There is no\nway to increase your regions quota past the 2MB limit.\n\n### Create a region using geotargets\n\nFor regions in Brazil and Russia, you can also use the `regions.create` method\nto create a region defined as a collection of geotargets, which are predefined\ngeographic areas. Examples of geotarget types include countries, states, cities,\nneighborhoods, and airports. However, the `regions` service currently only\nsupports the \"State\" type for Brazil and the \"Region\" type for Russia. To\ndownload a csv file of all geotarget IDs, including the geotargets that can be\nused with the `regions` service, see\n[Geotargets](/google-ads/api/reference/data/geotargets). The example below creates\na new region by providing the geotarget IDs of three Brazilian states.\n\nTo create the region, make a `POST` request using the following URL and request\nbody: \n\n https://shoppingcontent.googleapis.com/content/v2.1/\u003cvar translate=\"no\"\u003emerchantId\u003c/var\u003e/regions?regionId=123456\n\n {\n geoTargetAreas: {\n geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana\n }\n }\n\n### Use regions to create regional price overrides\n\nWhen you create a region, the `regions` service returns an response object that\nincludes a `regionId` and two [eligibility](#eligibility) status fields. If the\n`regionalInventoryEligible` value is `true`, you can use the `regionaliventory`\nservice to create an override that sets a different price for the region. The\nexample below creates a regional price override using the postal-code-based\nregion created in the example above, which has a `regionId` of \"456789\".\n\nTo create the override, make a `POST` request using the following URL and\nrequest body: \n\n https://shoppingcontent.googleapis.com/content/v2.1/\u003cvar translate=\"no\"\u003emerchantId\u003c/var\u003e/products/{productId}/regionalinventory\n\n {\n \"regionId\": \"456789\"\n \"price\": {\n value: \"10\"\n currency: \"USD\"\n },\n \"availability\": \"in stock\"\n }"]]