Neste tutorial, mostramos como criar e editar dados de local. Com a API My Business Business Information, você pode fazer o seguinte:
- Crie um novo local.
- Excluir um local
- Encontrar um local por nome de recurso.
- Listar todos os locais de uma conta
- Atualize um ou mais campos de um local.
Os locais podem ser usados no Google Ads, mas precisam ser verificado para estar qualificado para aparecem na Pesquisa e no Maps. Os dados de local são representados pelo accounts.locations coleção.
Antes de começar
Antes de usar a API My Business Business Information, você precisa registrar seu e receber as credenciais do OAuth 2.0. Para saber como começar com 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ê tem muitas empresas associadas à sua conta, pode ser útil obter um único local. Filtre por nome da empresa para receber um nome local 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, acrescente
googleUpdated ao 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, um código de status HTTP 404 NOT FOUND será
retornados. Clique aqui para ver mais detalhes sobre como gerenciar as atualizações do Google.
Listar locais
Se você gerencia um ou mais locais, todos os locais associados à sua conta. Use o accounts.locations.list API 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 para incluir o
fichas de empresa de propriedade indireta (pertencentes ou gerenciadas por um grupo):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrar resultados ao mostrar locais
É possível usar filtros para limitar os resultados retornados quando você chama accounts.locations.list. Para filtrar uma solicitação, anexe uma expressão de filtro ao URL de base, conforme mostrado em 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 (:). EQUALS (=) e HAS (:)
operadores são equivalentes para todos os campos, exceto locationName (consulte
na tabela abaixo).
As aspas são codificadas como "%22" e espaços como sinais de adição (+).
Salvo indicação em contrário, todas as comparações são tokens que não diferenciam maiúsculas de minúsculas e comparações. Por exemplo, "4 percursos" corresponderia 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 devem ser aplicadas à mesma
. 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 que se chama "Pepé Le Pew". Ele mostra categorias para "restaurante francês" ou "restaurante_europeu", e o rótulo "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 um determinado 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
A seguir está 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 |
A empresa nome real
|
categories |
Combinação da categoria principal e das categorias adicionais. Observe que a coluna "gcid:" precisa ser omitida. Se houver vários categorias, esse filtro faz a correspondência se pelo menos uma categoria corresponder 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 mais alta subdivisão administrativa, que é usada para endereços postais de um país ou região
|
storefront_address.locality |
A cidade/município do endereço
|
storefront_address.postal_code |
O CEP do endereço.
|
metadata.place_id |
Se o local foi verificado e está conectado ou aparece no Google Maps, esse campo é igual ao ID do local.
|
openInfo.status |
Indica se o local está aberto.
(
|
labels |
Uma coleção de strings de formato livre para que você inclua tags na sua empresa. Em em contraste com todos os outros campos, esse valor deve corresponder exatamente a um rótulo incluindo maiúsculas e minúsculas e não apenas um token. Por exemplo: Se um rótulo for "XX YY", depois nem "XX" ou "xx yy" vão coincidir.
|
storeCode |
O identificador externo deste 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
Você pode classificar os resultados por nome da empresa ou código da loja, em ordem crescente
em ordem decrescente. Vários critérios de ordenação são separados por vírgulas no
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 (link em inglês)
Para alterar um ou mais campos de um local, faça o seguinte:
Adicione os campos e os valores atualizados com o campo de local e use uma
lista separada por vírgulas de campos atualizados como o valor de fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}