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
shippingsettingsservice.
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
{
pos
tal
CodeArea
:
{
regio
n
Code
:
"US"
,
pos
tal
Codes
:
[
{
begi
n
:
"850*"
,
e
n
d
:
"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
{
geoTarge
t
Areas
:
{
geo
tar
ge
t
Cri
ter
iaId
:
[
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
{
“regio
n
Id”
:
"456789"
“price”
:
{
value
:
“
10
”
curre
n
cy
:
“USD”
},
“availabili
t
y”
:
“i
n
s
t
ock”
}
