Visão geral

A API do Perfil da Empresa no Google da V4MOS.AI entrega os registros brutos sincronizados das contas do Perfil da Empresa conectadas à sua organização: contas, locais, métricas diárias de desempenho, palavras-chave de busca e avaliações. As linhas vêm como foram sincronizadas, com os nomes de coluna do data warehouse (snake_case), prontas para levar ao seu BI. Todos os endpoints usam o prefixo /v1/google-business-profile e seguem a mesma autenticação, paginação e formato de resposta.

Primeiros passosCopiar link da seção

URL base: https://data.v4mos.ai. Toda chamada exige suas credenciais de API e o organizationId — veja Autenticação.

1. Conecte o Perfil da Empresa no Google em app.v4mos.ai (Contas conectadas) e aguarde a primeira sincronização.
2. Chame qualquer endpoint abaixo com o seu organizationId, por exemplo GET /v1/google-business-profile/reviews?organizationId=….
3. Toda linha traz integration_id e integration_name: a conexão de onde ela veio. Para ler uma conexão só, passe esse valor em integrationId.

Endpoints disponíveisCopiar link da seção

• getContas/v1/google-business-profile/accountsUma linha por conta do Perfil da Empresa no Google: nome, tipo e estado de verificação.
• getLocais/v1/google-business-profile/locationsUma linha por local: título, código da loja, site e as categorias, endereço, coordenadas, situação de funcionamento e metadados como JSON…
• getMétricas diárias de desempenho/v1/google-business-profile/daily-metricsUma linha por local, dia e métrica (cliques no site, ligações, pedidos de rota, conversas, reservas, pedidos de comida e impressões) com a…
• getPalavras-chave de busca/v1/google-business-profile/search-keywordsUma linha por local, mês e palavra-chave de busca, com o número de buscas.
• getAvaliações/v1/google-business-profile/reviewsNota, texto da avaliação, resposta do proprietário e datas.

RecursosCopiar link da seção

Paginação e filtrosCopiar link da seção

• page (padrão 1) e limit (padrão 500, máximo 5000). meta.hasNextPage diz se existe outra página; as linhas vêm sempre na mesma ordem, então avance as páginas até ele ser false.
• dateFrom / dateTo (YYYY-MM-DD, inclusivos) filtram pela coluna de data indicada na tabela acima. Recursos sem coluna de data recusam esses parâmetros.
• integrationId mantém só as linhas de uma conexão.
• As respostas ficam em cache por 30 minutos e os dados são sincronizados uma vez por dia — veja Sincronização de dados.

Formato da respostaCopiar link da seção

{
  "data": [{ "...": "um objeto por linha, com as colunas listadas em cada endpoint" }],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Contadores grandes (campos format: int64 no schema de cada endpoint) chegam como texto, por exemplo "1250", para não perder precisão. Converta para um tipo numérico do seu lado.