Neste tutorial, mostramos como criar e editar dados de local. Com a API My Business Business Information, você pode fazer o seguinte:
- Criar um local
- Excluir um local
- Encontrar um local por nome de recurso
- Exibir todos os locais de uma conta
- Atualizar um ou mais campos de um local
Os locais podem ser usados no Google Ads, mas precisam ser verificados para exibição na Pesquisa e no Maps. Os dados de local são representados pela coleção accounts.locations.
Antes de começar
Antes de usar a API My Business Business Information, é necessário registrar seu app e receber as credenciais do OAuth 2.0. Para saber como começar a usar essa API, consulte Configuração básica.
Criar um local
Você pode usar a API My Business Business Information para criar um novo local de uma empresa com accounts.locations.create.
Para criar um local, use o código abaixo:
POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False
{
"storeCode": "GOOG-SYD",
"languageCode": "en-AU",
"title": "Google Sydney",
"phoneNumbers": {
"primaryPhone": "02 9374 4000"
}
"storefrontAddress": {
"addressLines": [
"Level 5",
"48 Pirrama Road"
],
"locality": "Pyrmont",
"postalCode": "2009",
"administrativeArea": "NSW",
"regionCode": "AU"
},
"websiteUri": "https://www.google.com.au/",
"regularHours": {
"periods": [
{
"openDay": "MONDAY",
"closeDay": "MONDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "TUESDAY",
"closeDay": "TUESDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "WEDNESDAY",
"closeDay": "WEDNESDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "THURSDAY",
"closeDay": "THURSDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "FRIDAY",
"closeDay": "FRIDAY",
"openTime": "09:00",
"closeTime": "17:00"
}
]
},
"categories": {
"primaryCategory": {
"name": "gcid:software_company"
}
}
}
Excluir um local
Você pode usar a API My Business Business Information para excluir um local com locations.delete.
Para excluir um local, use o código abaixo:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Encontrar um local pelo nome
Se você tiver muitas empresas associadas à sua conta, recomendamos criar um único local. É possível filtrar pelo nome da empresa para encontrar um local específico com locations.get.
Para encontrar um local pelo nome, use o código abaixo: É necessário especificar um readMask para recuperar campos específicos. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Retornar a versão do Google Maps
Para retornar a versão do Google Maps de um local, insira googleUpdated no fim do URL da solicitação, como no exemplo abaixo:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Se nenhuma correspondência for encontrada, um código de status HTTP 404 NOT FOUND será retornado. Veja mais detalhes sobre como gerenciar as atualizações do Google aqui.
Listar locais
Ao gerenciar um ou mais locais, é recomendável listar todos aqueles que estão associados à sua conta. Use a API accounts.locations.list para listar todos os locais vinculados a um usuário.
Para criar uma lista de todos os locais de propriedade ou gerenciados por um usuário autenticado, use o seguinte:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Use um caractere curinga '-' para a conta no URL da solicitação de modo a incluir listas de propriedade indireta (de propriedade ou gerenciada por meio de um grupo):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrar resultados ao exibir locais
É possível usar filtros para limitar os resultados retornados quando você chama accounts.locations.list. Para filtrar uma solicitação, adicione uma expressão de filtro ao URL de base, conforme mostrado neste exemplo:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Sintaxe de consulta básica
Uma restrição tem a seguinte sintaxe: <field><operator><value>, em que o operador é EQUALS (=) ou HAS (:). Os operadores EQUALS (=) e HAS (:) são equivalentes a todos os campos, exceto locationName (veja a tabela abaixo).
As aspas são codificadas como "%22", e os espaços, como sinais de adição (+).
Exceto quando indicado, todas as comparações têm um formato de token indiferente a maiúsculas. Por exemplo, "4 drive" corresponde a "4, Privet Drive".
Combinar vários campos em uma consulta de filtro
A API permite que AND conecte todas as restrições de campos. No entanto, se você usar a palavra-chave OR, todas as restrições precisarão ser aplicadas ao mesmo campo. Por exemplo: locationName=A OR labels=B não é permitido.
Exemplo
O exemplo a seguir mostra uma expressão de filtro que retorna todos os locais com o nome "Pepé Le Pew" para as categorias "restaurante_francês" ou "restaurante_europeu" e com marcador "recém-inaugurado".
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Pesquisar por distância ou conta
O exemplo a seguir mostra como pesquisar locais em uma determinada distância de um ponto geográfico:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
Para filtrar locais em até 1.000 milhas de Binter, Colorado, EUA, use o código abaixo:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
Lista de todos os campos de filtro compatíveis
Veja a seguir uma lista completa de todos os campos que podem ser usados para filtragem:
| Campos | Descrição e exemplo |
|---|---|
| Campos de correspondência de string | |
title |
Nome real da empresa.
|
categories |
Combinação da categoria principal e das categorias adicionais. "gcid:" precisa ser omitido. Se houver várias categorias, esse filtro corresponderá a pelo menos uma que atenda a esse padrão.
|
phone_numbers.primary_phone |
Número de telefone principal no formato E.164 (por exemplo: "+441234567890").
|
storefront_address.region_code |
Código regional CLDR do país/região do endereço.
|
storefront_address.administrative_area |
A subdivisão administrativa mais abrangente usada para endereços postais de um país ou uma região.
|
storefront_address.locality |
Cidade do endereço.
|
storefront_address.postal_code |
CEP do endereço.
|
metadata.place_id |
Se o local tiver sido verificado e estiver conectado ao Google Maps ou exibido nele, esse campo será preenchido com o ID do local.
|
openInfo.status |
Indica se o local está aberto (
|
labels |
Uma coleção de strings de formato livre para que você adicione tags à sua empresa. Diferentemente dos outros campos, esse valor precisa corresponder exatamente a um marcador completo, incluindo letras maiúsculas e minúsculas, e não apenas um token. Por exemplo, "XX" e "xx yy" não serão correspondentes a um marcador "XX YY".
|
storeCode |
Identificador externo desse local, que precisa ser exclusivo em uma determinada conta.
|
| Funções | |
distance |
Permite filtrar com base na distância do local a partir de um ponto geográfico.
|
Classificar por campo de consulta
É possível classificar os resultados por nome da empresa ou código da loja, em ordem crescente ou decrescente. Vários critérios de ordenação são separados por vírgulas na string orderBy, como no exemplo abaixo:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Aplicar patch a um local
Use a API My Business Business Information para atualizar um ou mais campos de um local com locations.patch.
Para alterar um ou mais campos de um local, use o código abaixo:
Adicione os campos e os valores atualizados ao campo de local e use uma lista separada por vírgulas de campos atualizados como valor para fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}