Neste tutorial, mostramos como criar e editar dados de local. Com a API My Business Business Information, você pode:
- Criar um novo local.
- Excluir um local
- Conferir um local pelo nome do recurso.
- Listar 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 aparecerem 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, você precisa registrar seu aplicativo e receber as credenciais do OAuth 2.0. Para saber como começar a usar a API My Business Business Information, consulte Configuração básica.
Criar um local
Você pode usar a API My Business Business Information para criar um novo local para uma empresa com accounts.locations.create.
Para criar um local, use o seguinte:
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 seguinte:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Encontrar um local pelo nome
Se você tiver muitas empresas associadas à sua conta, convém ter 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. É preciso especificar uma 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, inclua googleUpdated no URL da solicitação, como no exemplo a seguir:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Se não houver resultados, será retornado um código de status HTTP 404 NOT FOUND. Veja mais detalhes sobre como gerenciar as atualizações do Google aqui.
Listar locais
Se você gerencia um ou mais locais, pode mostrar todos aqueles que estão associados à sua conta. Use a API accounts.locations.list para listar todos os locais associados a um usuário.
Para listar 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 com o objetivo de incluir fichas de propriedade indireta (de propriedade ou gerenciadas por meio de um grupo):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrar resultados ao listar locais
Você pode usar filtros para limitar os resultados retornados quando chama accounts.locations.list. Para filtrar uma solicitação, anexe uma expressão de filtro ao URL base, como 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 para todos os campos, exceto locationName (consulte a tabela abaixo).
As aspas são codificadas como "%22" e os espaços como sinais de adição (+).
A menos que indicado de outra forma, todas as comparações são de tokens indiferentes 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, quando se trata da palavra-chave OR, todas as restrições precisam ser aplicadas ao mesmo campo. Por exemplo: locationName=A OU 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". Ele mostra categorias para "restaurante_francês" ou "restaurante_europeu" e um rótulo "recém-aberto".
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 a 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 um raio de 1.000 milhas de Boulder, Colorado, EUA:
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 |
A combinação da categoria principal e das categorias adicionais. O "gcid:" precisa ser omitido. Se houver várias categorias, esse filtro fará a correspondência se pelo menos uma categoria corresponder a esse padrão.
|
phone_numbers.primary_phone |
O número de telefone principal no formato E.164 (por exemplo: "+441234567890").
|
storefront_address.region_code |
O código regional CLDR do país/região do endereço.
|
storefront_address.administrative_area |
A subdivisão administrativa mais alta 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á igual ao ID do local
|
openInfo.status |
Indica se o local está aberto (
|
labels |
É uma coleção de strings de formato livre para incluir tags na sua empresa. Ao contrário de todos os outros campos, esse valor precisa corresponder exatamente a um rótulo completo, incluindo letras maiúsculas e minúsculas, e não apenas um token. Por exemplo, se um rótulo for "XX YY", "XX" ou "xx yy" não serão correspondentes.
|
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.
|
Ordenar 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 a seguir:
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 com o campo de localização e use uma lista separada por vírgulas de campos atualizados como o valor para fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}