Visão Geral
Visão geral da API do Google Analytics da V4MOS.AI
A API do Google Analytics da V4MOS.AI centraliza dados de sessões, eventos, eventos personalizados, clientes, produtos e transações das propriedades GA4 conectadas ao seu organization. Todos os endpoints ficam sob o prefixo /v1/google-analytics e seguem os mesmos padrões de autenticação, paginação e resposta da plataforma.
Endpoints Disponíveis
- getSessões
/v1/google-analytics/sessionsRetorna sessões do Google Analytics com métricas de campanha, página e origem de tráfego. - getEventos
/v1/google-analytics/eventsRetorna eventos do Google Analytics com métricas de engajamento. - getEventos personalizados
/v1/google-analytics/custom-eventsRetorna eventos personalizados do Google Analytics com mapeamentos de métricas. - getClientes
/v1/google-analytics/customersRetorna métricas de clientes do Google Analytics com segmentação geográfica e por dispositivo. - getProdutos
/v1/google-analytics/productsRetorna métricas de produtos de e-commerce do Google Analytics. - getTransações
/v1/google-analytics/transactionsRetorna métricas de transações do Google Analytics. - getEngagement
/v1/google-analytics/engagementSite engagement of the period from GA4: sessions, engaged sessions, bounce rate and average engagement time per session per day, in total… - getEvents by device
/v1/google-analytics/events-by-deviceGA4 events of the period summed per event and device category, for the audit (carts addtocart, purchases purchase, leads formsubmit, ...). - getProducts by device
/v1/google-analytics/products-by-deviceGA4 product funnel of the period summed per device category, for the audit: product views, carts, checkouts, purchases and item revenue,… - getLanding sessions
/v1/google-analytics/landing-sessionsGA4 sessions of the period by default channel group and by landing page, with the previous window (the same number of days right before…
Autenticação
Todos os endpoints exigem o query parameter organizationId. Todos, menos as rotas da auditoria (/events-by-device, /products-by-device e /landing-sessions), autenticam com os headers x-client-id e x-client-secret; as rotas da auditoria só aceitam Bearer token (detalhes mais abaixo, nas rotas por aparelho). Veja Autenticação.
Parâmetros Comuns
organizationId(obrigatório) – Organização que possui a integração do Google AnalyticsuserId– Escopo de usuáriopage– Número da página (padrão: 1)limit– Registros por página (padrão: 500, máx: 5000)createdStart/createdEnd– Filtro por intervalo de datas (ISO 8601)
Filtros Específicos por Recurso
Sessões (/v1/google-analytics/sessions)
createdStart/createdEnd
Eventos (/v1/google-analytics/events)
createdStart/createdEnd
Eventos Personalizados (/v1/google-analytics/custom-events)
createdStart/createdEnd
Clientes (/v1/google-analytics/customers)
createdStart/createdEnd
Produtos (/v1/google-analytics/products)
createdStart/createdEnd
Transações (/v1/google-analytics/transactions)
createdStart/createdEnd
Engajamento (/v1/google-analytics/engagement)
startDate/endDate(obrigatórios,YYYY-MM-DD, UTC, até 366 dias); sem paginação- Devolve sessões, sessões engajadas e taxa de rejeição (
(1 - sessões engajadas / sessões) * 100) por dia, no total e por aparelho engagementSeconds: tempo médio de engajamento por sessão do GA4, em segundos (userEngagementDuration / sessions:SUM(user_engagement_duration) / SUM(sessions), só nas linhas que têm a medida); num período com backfill parcial é a média dos dias medidos, enquanto sessões e rejeição contam todos os dias;nullpara dado do GA4 carregado antes do backfill do tempo de engajamento
Eventos por aparelho (/v1/google-analytics/events-by-device)
startDate/endDate(obrigatórios,YYYY-MM-DD, UTC, até 366 dias);eventNamesopcional (separados por vírgula, até 50); sem paginação- Devolve por evento (ex.:
add_to_cart,purchase,form_submit) contagem, eventos-chave, valor e transações do período, no total e por aparelho
Produtos por aparelho (/v1/google-analytics/products-by-device)
startDate/endDate(obrigatórios,YYYY-MM-DD, UTC, até 366 dias); sem paginação- Devolve visualizações de produto, carrinhos, checkouts, compras e receita de item do período, somando todos os produtos, no total e por aparelho
As duas rotas por aparelho são da auditoria: só aceitam Bearer token de kind user ou oaclient emitido para a aplicação V4MOS. O par x-client-id / x-client-secret e service accounts de cliente recebem 403.
Sessões por página de entrada (/v1/google-analytics/landing-sessions)
startDate/endDate(obrigatórios,YYYY-MM-DD, UTC, até 366 dias); sem paginação- Devolve sessões, sessões engajadas e taxa de rejeição por grupo de canal (com as sessões do período anterior, de mesmo tamanho) e as 10 páginas de entrada com mais sessões
- Também é da auditoria: mesmo acesso das rotas por aparelho (Bearer
userouoaclient; o par e service accounts recebem 403)
Destaques do Modelo de Dados do Google Analytics
Sessões
- Campanhas e tráfego:
campaign_id,campaign_name,source_medium,session_source_medium - Páginas:
page_title,page_path - Usuários e sessões:
sessions,total_users,new_users,engaged_sessions,sessions_per_user - Data:
date
Eventos
- Identificação:
event_name,date - Métricas:
event_count,event_count_per_user,event_value,events_per_session,key_events
Eventos Personalizados
- Identificação:
event_name,event_date - Métricas:
metric_name,metric_value - Mapeamento RD Station:
custom_rd_action,custom_rd_asset_id,custom_rd_filter - Categoria:
custom_event_category,custom_event_label
Clientes
- Campanhas e segmentação:
campaign_id,campaign_name,device_category,source_medium - Geografia:
city,region,country - Audiência:
active_users,total_users,sessions,engaged_sessions,bounce_rate - Receita:
purchase_revenue,total_revenue,total_purchases,purchaser_rate - Data:
date
Produtos
- Identificação:
item_id,item_name - Receita e compras:
item_revenue,items_purchased - Interações:
items_viewed,items_added_to_cart,items_checked_out,items_clicked_in_promotion,item_list_click_through_rate - Data:
date
Transações
- Identificação:
event_name,date - Métricas:
transactions,transactions_per_purchaser
Respostas
Todas as respostas seguem o padrão:
{
"data": [...],
"meta": {
"page": 1,
"limit": 500,
"hasNextPage": true,
"hasPreviousPage": false
}
}