O serviço regions
permite criar e gerenciar regiões geográficas que podem ser usadas como destinos com os serviços regionalinventory
e shippingsettings
. É possível definir regiões como coleções de códigos postais ou, em alguns países, usando segmentações geográficas predefinidas. Neste guia, fornecemos exemplos de como definir cada tipo de região e como criar uma modificação de preços regional. Para mais informações sobre o serviço regions
,
incluindo todos os métodos e parâmetros disponíveis, consulte a documentação de referência.
Qualificação por região
Quando você cria uma região, o serviço de regiões determina se é possível usá-la
com outros serviços da API Content. O objeto de resposta retornado para uma chamada regions.create
bem-sucedida inclui dois campos booleanos, regionalInventoryEligible
e shippingEligible
, que indicam se é possível usar a região com os serviços regionalinventory
e shippingsettings
, respectivamente.
regionalInventoryEligible
Para se qualificar para uso com o serviço regionalinventory
, uma região precisa atender aos seguintes critérios:
- O
regionId
, que você especifica ao criar uma região, precisa conter apenas dígitos e pelo menos seis dígitos. - A região precisa atender aos requisitos mínimos de tamanho para a área geográfica e a população on-line.
shippingEligible
Para se qualificar para uso com o serviço shippingsettings
, uma região precisa atender aos seguintes critérios:
- A região precisa ser definida usando CEPs/códigos postais.
- A região precisa fazer parte de um país compatível com o serviço
shippingsettings
.
Exemplos
Este é um exemplo de código completo que pode ser usado para criar uma nova região em 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(); } }
Criar uma região usando códigos postais
É possível usar o método regions.create
para criar uma região definida como uma coleção de códigos postais. O exemplo abaixo cria uma nova região para o estado do Arizona, EUA, especificando um intervalo de códigos postais.
Para criar a região, faça uma solicitação POST
com o seguinte URL e corpo:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789
{
postalCodeArea: {
regionCode: "US",
postalCodes: [
{
begin: "850*",
end: "860*"
}
]
}
}
Há um limite rígido de 2 MB de dados para regions
e shippingsettings
por conta do Merchant Center. As configurações de frete e região
são copiadas internamente de uma MCA para todas as subcontas. Portanto, em MCAs maiores, talvez você atinja rapidamente o limite de armazenamento. Nesse caso, uma solução alternativa é gerenciar regions
e shippingsettings
no nível do ID do comerciante. Não é possível aumentar a cota das regiões além do limite de 2 MB.
Criar uma região usando segmentações geográficas
Para regiões do Brasil e da Rússia, também é possível usar o método regions.create
para criar uma região definida como uma coleção de segmentações geográficas, que são áreas geográficas predefinidas. Exemplos de tipos de segmentação geográfica incluem países, estados, cidades, bairros e aeroportos. No entanto, o serviço regions
atualmente oferece
suporte apenas ao tipo "Estado" para o Brasil e o tipo "Região" para a Rússia. Para fazer o download de um arquivo csv de todos os IDs de segmentação geográfica, incluindo as segmentações geográficas que podem ser usadas com o serviço regions
, consulte Segmentações geográficas. O exemplo abaixo cria uma nova região fornecendo os IDs de segmentação geográfica de três estados brasileiros.
Para criar a região, faça uma solicitação POST
usando o seguinte URL e o seguinte corpo:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456
{
geoTargetAreas: {
geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
}
}
Usar regiões para criar substituições de preço regionais
Quando você cria uma região, o serviço regions
retorna um objeto de resposta que
inclui um regionId
e dois campos de status de qualificação. Se o
valor regionalInventoryEligible
for true
, será possível usar o serviço regionaliventory
para criar uma substituição que defina um preço diferente para a região. O exemplo abaixo cria uma substituição de preço regional usando a região baseada em código postal criada no exemplo acima, que tem um regionId
de "456789".
Para criar a substituição, faça uma solicitação POST
usando o seguinte URL e
o corpo da solicitação:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory
{
“regionId”: "456789"
“price”: {
value: “10”
currency: “USD”
},
“availability”: “in stock”
}