Voltar para o blog

Conector Google Business Profile: avaliações, localizações e métricas de performance no seu data warehouse

Erathos lança conector gerenciado do Google Business Profile: sincronize avaliações, localizações, posts e métricas no seu data warehouse.

New Connector - Google My Business

A Erathos está lançando o conector gerenciado para o Google Business Profile, a API por trás do Google Business Profile. Vinte e dois endpoints disponíveis, dez destinos suportados, zero código de pipeline para escrever ou manter.

O Google Business Profile expõe seus dados por meio da API do Google Business Profile, autenticada com OAuth 2.0, o que em teoria permite construir sua própria extração. Na prática, isso significa escrever e manter um pipeline ETL customizado para lidar com um ciclo de vida de token OAuth que renova a cada hora, uma quota que começa em zero até o Google aprovar seu projeto no Cloud, e cadeias de recursos que multiplicam requests em todas as localizações da conta, algo que a maioria dos times de dados só descobre tarde demais que não escala. O conector da Erathos resolve essa integração como um serviço gerenciado, sem código para o seu time escrever ou manter.

Todo negócio com múltiplas localizações que quer entender como se sai no Google Search e no Maps bate na mesma parede: avaliações, fotos, posts e insights de performance vivem dentro do console do Google Business Profile, com dashboards por localização, o resto do stack de analytics vive no warehouse, e unir os dois se transforma em um projeto de engenharia que ninguém planejou. O que começa como um script Python rodando a dança do OAuth no cron de uma VM vira, três meses depois, um pipeline que ninguém entende, que falha em silêncio e que nenhum engenheiro quer herdar.

O problema dos pipelines do Google Business Profile construídos à mão

A API do Google My Business se autentica com OAuth 2.0 em vez de um token estático, e cada dado depende de uma conta e das localizações dela. O padrão parece simples o bastante para construir em uma tarde com uma das bibliotecas cliente do Google. O custo real aparece depois, e é previsível.

Não existe API key estática. O acesso à API do Business Profile exige um cliente OAuth, uma tela de consentimento OAuth configurada com o escopo business.manage e uma troca de tokens que produz um refresh token. Access tokens expiram após cerca de uma hora, então um pipeline caseiro precisa renovar os tokens por conta própria, persistir o refresh token com segurança e se recuperar quando uma senha muda ou o acesso é revogado. Um fluxo de renovação feito à mão falha com um 401 opaco, geralmente no pior momento possível.

A quota começa em zero. A quota padrão da API do Google é 0 até o projeto no Cloud ser aprovado para Basic API Access, e mesmo depois da aprovação existe um rate limit de 300 queries por minuto por API, além de limites diários por endpoint. Uma sincronização que abrange dezenas ou centenas de localizações estoura os limites diários no meio da execução, e o código que não detecta o limite simplesmente para de buscar no meio do caminho e reporta sucesso.

Todo recurso é uma cadeia. Reviews, mídias, mídias de clientes, posts, menus, serviços, admins, verificações e métricas são todas subcoleções de cada localização, e as localizações dependem de cada conta. Uma marca com 300 localizações multiplicada por um punhado de endpoints por localização resulta em milhares de requests paginados por execução, todos dentro de limites diários por endpoint. Perca uma página ou uma localização, e o warehouse guarda um snapshot parcial sem nenhum erro.

Métricas que exigem tratamento especial. As métricas diárias de performance chegam como uma time series de pares de data e valor por localização, e as impressões de palavras-chave de busca chegam como agregados mensais por localização. A lógica de iteração, métrica por localização por janela, é onde linhas duplicadas e dias ausentes entram em silêncio, porque uma lacuna em uma time series é dado válido, não um erro.

Reviews são mutáveis. Clientes editam comentários e anexam mídias depois de publicar, e as respostas do próprio negócio mudam ao longo do tempo. O Google só envia notificações de novas reviews se você configurar o Pub/Sub por conta própria; sem isso, o pipeline precisa reler cada localização em um cronograma, e uma extração pontual captura um objeto em movimento. Os dashboards continuam mostrando estados de reviews desatualizados sem que nenhum erro apareça em lugar nenhum.

Evolução de schema sem aviso. A linha de uma localização carrega dezenas de campos aninhados: endereço, horários, coordenadas, informações de funcionamento, metadados. Attributes, serviços e menus chegam como JSON. Quando o Google adiciona attributes para uma categoria ou uma nova métrica aparece na série, o loader que achata um conjunto fixo de colunas ou quebra ou descarta o novo campo em silêncio. A inconsistência chega ao dashboard antes de chegar ao seu monitoramento.

Observabilidade que não existe. Um 200 OK em todos os requests não significa que os dados chegaram completos. Sem uma contagem de registros por endpoint por execução, sem comparação com a janela anterior, sem alerta de queda de volume, uma sincronização que silenciosamente pulou metade das localizações depois de atingir um limite diário parece exatamente com uma saudável.

O pior cenário não é o pipeline que quebra e envia um alerta. É o pipeline que roda com sucesso e entrega dados errados, e a nota média que chega ao dashboard da liderança já foi calculada sobre uma base incompleta.

O que você pode fazer quando os dados do Google Business Profile chegam ao seu warehouse

Antes de entrar no conector em si, vale documentar o que você realmente ganha quando reviews, localizações e métricas de performance saem do Google e chegam modeladas ao lado do resto do seu stack.

Operação de reviews em todas as localizações, não uma de cada vez

Com reviews e admins de localização no warehouse, você calcula nota média, volume de reviews, taxa de resposta e tempo até responder por localização, por gestor e por semana, e acompanha a distribuição de notas em estrelas se deslocar ao longo do tempo. A interface do Google reporta um perfil por vez; comparar centenas de localizações entre si e com suas próprias dimensões operacionais, time, região, franquia, exige as linhas brutas no warehouse.

Reviews cruzadas com receita e o CRM

Cruzar a atividade de reviews por localização com vendas por unidade responde à pergunta que todo negócio com múltiplas localizações faz: uma queda de nota precede uma queda de receita, e com quanta antecedência? Cruzar os perfis dos avaliadores com a base de contatos do seu CRM encaminha clientes insatisfeitos ao time de retenção antes do churn. Isso só é possível com o Google My Business e o CRM no mesmo warehouse, unidos por um campo de negócio.

O que os clientes locais realmente pesquisam

O searchkeyword_impressions_monthly registra quais termos de busca geraram impressões para cada localização, e o daily_metrics_time_series acompanha como impressões, ligações e solicitações de rota evoluem ao longo do tempo. Na rede inteira, isso se transforma em um mapa de demanda local por cidade e por produto, que alimenta SEO local, copy de anúncios, estoque das lojas e decisões de expansão. O console do Google mostra os números de cada localização; a análise cruzada entre localizações exige o warehouse.

Uma auditoria de qualidade de dados de toda a rede

A tabela de localizações, com place action links, listas de serviços e verificações, permite auditar a rede como dado: localizações sem horário de funcionamento ou sem categoria principal, links de booking e pedidos mortos ou duplicados, números de telefone que não batem mais com o sistema de registro, perfis travados em verificação pendente. Um score de qualidade de dados por localização, entregue às equipes de franquia e operações toda manhã, é uma query no warehouse, não clicar manualmente em centenas de perfis.

Ofertas e menus padronizados entre unidades

Com cardápios, listas de serviços e detalhes de hospedagem no warehouse, redes comparam menus, preços e serviços entre unidades, apontam lacunas de padronização e reconciliam o que é oferecido no Google com o que os dados de POS e de produto dizem que é de fato vendido. Um grupo hoteleiro audita atributos de hospedagem entre propriedades; uma rede de restaurantes identifica unidades cujo cardápio no Google divergiu do oficial.

Fotos de clientes e seguidores como sinais de engajamento

O customer_media e o followers_metadata transformam conteúdo gerado por usuários em métrica: quais localizações recebem clientes subindo fotos, como o volume de fotos e as contagens de seguidores evoluem ao longo do tempo, e como esses sinais se relacionam com o volume de reviews e a receita. Conteúdo gerado por usuários por unidade é um indicador antecedente que nenhum console nativo agrega em toda a rede.

O que está disponível no conector

O conector do Google My Business entrega vinte e dois endpoints prontos para serem materializados no seu warehouse de destino:

Endpoint

O que contém

account_admins

Admins de cada conta do Business Profile, com papel e status de convite pendente

account_invitations

Convites pendentes em cada conta, com papel e a conta ou localização de destino

accounts

Contas do Business Profile que o usuário autorizado gerencia, com nome, tipo, papel, estado de verificação, número da conta e informações da organização

attributes

Definições de attributes disponíveis para uma localização dada a sua categoria principal e o seu país, com tipo de valor, grupo e nomes de exibição

categories

Categorias de negócio suportadas pelo Google, com nomes de exibição, tipos de serviço e tipos de horários adicionais

customer_media

Itens de mídia que clientes contribuíram para cada localização, com formato, URLs, dimensões e atribuição

daily_metrics_time_series

Métricas diárias de performance por localização como uma time series de pares de data e valor, como impressões, ligações e solicitações de rota

followers_metadata

Metadados de seguidores de cada localização, com a contagem de seguidores

food_menus

Cardápios de cada localização, com seções, rótulos, tipos de cozinha e URL de origem

local_posts

Posts locais publicados em cada localização: resumo, tipo de tópico, call to action, mídias, detalhes de oferta e de evento, e horários agendados

location_admins

Admins e gestores de cada localização, com papel e status de convite pendente

locations

Cada localização em cada conta: código da loja, endereço, telefones, categorias principal e adicionais, site, horários regulares e especiais, área de serviço, coordenadas, labels e estado de funcionamento

lodging

Detalhes de hospedagem para localizações do tipo hotel: propriedade e serviços, políticas, alimentação e bebidas, bem-estar, acessibilidade, sustentabilidade e unidades para hóspedes

media

Itens de mídia que o negócio enviou para cada localização, com formato, dimensões, URLs e associação à localização

place_action_links

Links de ação configurados em cada localização, como URLs de booking, pedidos ou reservas, com tipo de ação, provedor e URI

place_action_type_metadata

Metadados dos tipos de ação de lugar suportados, com nomes de exibição

recommended_google_locations

Localizações do Google recomendadas para cada conta, correspondências potenciais ainda não reivindicadas, com a URL para solicitar direitos de admin

reviews

Reviews de clientes de cada localização: avaliador, nota em estrelas, comentário, mídias anexadas à review, datas de criação e atualização, e a resposta do negócio

searchkeyword_impressions_monthly

Impressões mensais de palavras-chave de busca de cada localização: quais termos de busca geraram impressões e seus valores agregados

service_list

Serviços oferecidos por cada localização, com preço e descrições estruturadas ou em texto livre

verifications

Tentativas de verificação de cada localização, com método, estado, data de criação e anúncio

voice_of_merchant_state

Se cada localização detém o controle de voice of merchant, com condições pendentes como verificação, conflitos de propriedade ou conformidade com as diretrizes

Todos os vinte e dois endpoints sincronizam como full refresh, o que combina com a forma como a API do Business Profile expõe esses dados: recursos por localização e time series sem um cursor incremental estável para usar como chave. Os relacionamentos entre entidades são preservados no destino: accounts são o pai de account admins, account invitations, locations e recommended Google locations, e as locations são o pai de reviews, mídias, customer media, posts, menus, serviços, admins, métricas, verificações e merchant state.

Como autenticar

  • Client ID: o client ID OAuth 2.0 do seu projeto no Google Cloud, usado para identificar a conexão.
  • Client Secret: o secret que acompanha o Client ID na troca de tokens do OAuth 2.0.
  • Sign in with Google: uma autorização única da conta Google que gerencia seus Business Profiles, concedida com o escopo https://www.googleapis.com/auth/business.manage.

Onde encontrá-los: abra o Google Cloud Console em console.cloud.google.com, crie ou selecione um projeto, habilite a família de APIs do Google Business Profile em APIs & Services, Library, configure a tela de consentimento OAuth adicionando o escopo business.manage e crie um client ID OAuth do tipo Web application em APIs & Services, Credentials. Copie o Client ID e o Client Secret gerados, cole-os no formulário do conector da Erathos, complete o passo de Sign in with Google com a conta que gerencia seus perfis e clique em Save and close depois que o Google redirecionar você de volta. A Erathos armazena o refresh token e renova automaticamente o access token, válido por cerca de uma hora.

Um detalhe de quota que vale planejar: a quota padrão da API do Google é 0 até o projeto no Cloud ser aprovado para Basic API Access, o que traz um rate limit de 300 queries por minuto por API, além de limites diários por endpoint, então solicite a aprovação antes de agendar sua primeira sincronização.

O processo completo está documentado no guia do conector em docs.erathos.com/connectors/apis/google-my-business.

Por que terceirizar a ingestão com a Erathos

A premissa por trás do conector é direta: o trabalho de engenharia de manter a ingestão não deveria ser responsabilidade do seu time de dados. O ciclo de vida do token OAuth, quota e limites diários, cadeias de requests em todas as localizações, mutações de reviews, evolução de schema, alertas de falha, alertas de queda de volume, backfills. Tudo isso é responsabilidade de quem opera a plataforma de ingestão. Depois que o conector está configurado, a plataforma entrega:

Visibilidade de ponta a ponta de cada execução

Tempo de extração por endpoint, contagem de registros por execução, quais contas e localizações foram processadas, onde houve retries. Quando uma métrica muda no dashboard e algum time abre um ticket com o time de dados, você tem a trilha completa para encontrar a causa raiz.

Alertas configurados de fábrica

Falhas de execução, quedas de volume por endpoint e atrasos de janela são detectados e roteados pelas integrações de alertas que seu time já usa, como Slack e e-mail. Você não escreve esse código.

Reprocessamento como operação suportada

Como o conector roda um full refresh, capturar uma resposta de review publicada ontem ou um menu atualizado é questão de rodar a sincronização novamente, não de reconstruir estado com sequências improvisadas de DELETE + INSERT. Quando você precisa reprocessar um período, por exemplo depois de mudar a lógica do modelo de reviews ou corrigir um período afetado por um problema de quota, isso é uma operação da plataforma.

Renovação correta de tokens, gestão de quota, paginação em centenas de localizações e reprocessamento são responsabilidade da plataforma. O time de dados foca no modelo, não no encanamento.

Pipelines disponíveis

O conector do Google Business Profile está disponível com os seguintes destinos:

Comece agora

Crie sua conta Erathos em https://app.erathos.com/signup?slug=blog&button=cta&utm_campaign=google-my-business_release e conecte o Google Business Profile ao seu warehouse em minutos. Com o Client ID e o Client Secret do seu Google Cloud mais uma autorização única de Sign in with Google, seus primeiros dados chegam ao destino com zero código de pipeline para escrever, manter ou monitorar.

Reviews de clientes e dados de busca local gerados todos os dias não devem ficar presos dentro de um SaaS, desconectados do resto do seu modelo de analytics. Ou pior: presos em um pipeline caseiro que vai seguir custando a atenção do seu time todo mês, para sempre.

Veja a documentação completa do conector em https://docs.erathos.com/connectors/apis/google-my-business.