Estatísticas de busca

Mostra quantas buscas a vitrine recebeu, quantas não acharam nada, a taxa de clique e quais termos são mais buscados ou ficam sem resultado.

Os termos que os clientes digitam são o melhor mapa do que eles querem comprar. Estas duas rotas mostram esse mapa: o resumo diz quanto a busca está funcionando, e a lista de termos mostra o que procuram e, principalmente, o que procuram e não acham, que é a lista de produtos, sinônimos e redirecionamentos que valem cadastrar. Exigem o privilégio manage_settings.

Só entra na conta a busca enviada (o cliente apertou Enter). O autocompletar enquanto digita não é registrado, e termos vazios também não.

GET/api/v1/admin/search/analytics/summaryAdmin

Resumo das buscas da vitrine

Soma o período pedido: buscas, taxa de buscas sem resultado, taxa de clique, conversões e receita.

Parâmetros de consulta

daysintegerpadrão: 30

Últimos N dias, de 1 a 365. Fora disso volta a 30.

fromstring

Início do período, YYYY-MM-DD. Só vale se to também vier e as duas datas forem válidas; nesse caso substitui days. Datas invertidas são trocadas.

tostring

Fim do período, YYYY-MM-DD, incluindo o dia.

GET/api/v1/admin/search/analytics/termsAdmin

Termos mais buscados ou sem resultado

Lista os termos do período, já normalizados (minúsculas, sem acento), com os números de cada um.

Parâmetros de consulta

kindstringpadrão: top

topzero

top ordena por número de buscas. zero mostra só termos que tiveram ao menos uma busca sem resultado, do pior para o melhor.

limitintegerpadrão: 50

Quantos termos, de 1 a 200. Fora disso volta a 50.

daysintegerpadrão: 30

Últimos N dias, de 1 a 365.

fromstring

Início, YYYY-MM-DD (com to).

tostring

Fim, YYYY-MM-DD.

Exemplo de requisição

bash

# os 20 termos que mais deram "nada encontrado" em outubro
curl "$BASE_URL/api/v1/admin/search/analytics/terms?kind=zero&limit=20&from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $TOKEN"

curl "$BASE_URL/api/v1/admin/search/analytics/summary?days=7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo

json

{
  "searches": 11,
  "zero_results_pct": 0.09090909090909091,
  "ctr": 0.09090909090909091,
  "conversions": 0,
  "revenue_cents": 0
}

200Termos

json

{
  "terms": [
    { "query_norm": "camiseta", "searches": 9, "zero_results": 0, "clicks": 1, "conversions": 0, "revenue_cents": 0 },
    { "query_norm": "cadeira gamer", "searches": 6, "zero_results": 6, "clicks": 0, "conversions": 0, "revenue_cents": 0 }
  ]
}

Campos do resumo

searchesinteger

Buscas enviadas no período.

zero_results_pctnumber

Fração das buscas que não devolveram resultado, de 0 a 1 (0.1 é 10%).

ctrnumber

Fração das buscas em que o cliente clicou em um resultado, de 0 a 1.

conversionsinteger

Compras atribuídas a uma busca.

revenue_centsinteger

Receita dessas compras, em centavos.

Campos de cada termo

query_normstring

Termo normalizado.

searchesinteger

Vezes que foi buscado.

zero_resultsinteger

Vezes que não achou nada.

clicksinteger

Vezes em que houve clique em um resultado.

conversionsinteger

Compras atribuídas ao termo.

revenue_centsinteger

Receita atribuída, em centavos.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_settings`	`{"error":"insufficient privileges","required":"manage_settings"}`
503	O serviço de estatísticas não está disponível	`{"error":"search analytics unavailable"}`
500	Falha ao calcular	`{"error":"failed to compute summary","detail":"..."}`

Veja também

Estatísticas de busca

Mostra quantas buscas a vitrine recebeu, quantas não acharam nada, a taxa de clique e quais termos são mais buscados ou ficam sem resultado.

Só entra na conta a busca enviada (o cliente apertou Enter). O autocompletar enquanto digita não é registrado, e termos vazios também não.

GET/api/v1/admin/search/analytics/summaryAdmin

Resumo das buscas da vitrine

Soma o período pedido: buscas, taxa de buscas sem resultado, taxa de clique, conversões e receita.

Parâmetros de consulta

daysintegerpadrão: 30

Últimos N dias, de 1 a 365. Fora disso volta a 30.

fromstring

Início do período, YYYY-MM-DD. Só vale se to também vier e as duas datas forem válidas; nesse caso substitui days. Datas invertidas são trocadas.

tostring

Fim do período, YYYY-MM-DD, incluindo o dia.

GET/api/v1/admin/search/analytics/termsAdmin

Termos mais buscados ou sem resultado

Lista os termos do período, já normalizados (minúsculas, sem acento), com os números de cada um.

Parâmetros de consulta

kindstringpadrão: top

topzero

top ordena por número de buscas. zero mostra só termos que tiveram ao menos uma busca sem resultado, do pior para o melhor.

limitintegerpadrão: 50

Quantos termos, de 1 a 200. Fora disso volta a 50.

daysintegerpadrão: 30

Últimos N dias, de 1 a 365.

fromstring

Início, YYYY-MM-DD (com to).

tostring

Fim, YYYY-MM-DD.

Exemplo de requisição

bash

# os 20 termos que mais deram "nada encontrado" em outubro
curl "$BASE_URL/api/v1/admin/search/analytics/terms?kind=zero&limit=20&from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $TOKEN"

curl "$BASE_URL/api/v1/admin/search/analytics/summary?days=7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Resumo

json

{
  "searches": 11,
  "zero_results_pct": 0.09090909090909091,
  "ctr": 0.09090909090909091,
  "conversions": 0,
  "revenue_cents": 0
}

200Termos

json

{
  "terms": [
    { "query_norm": "camiseta", "searches": 9, "zero_results": 0, "clicks": 1, "conversions": 0, "revenue_cents": 0 },
    { "query_norm": "cadeira gamer", "searches": 6, "zero_results": 6, "clicks": 0, "conversions": 0, "revenue_cents": 0 }
  ]
}

Campos do resumo

searchesinteger

Buscas enviadas no período.

zero_results_pctnumber

Fração das buscas que não devolveram resultado, de 0 a 1 (0.1 é 10%).

ctrnumber

Fração das buscas em que o cliente clicou em um resultado, de 0 a 1.

conversionsinteger

Compras atribuídas a uma busca.

revenue_centsinteger

Receita dessas compras, em centavos.

Campos de cada termo

query_normstring

Termo normalizado.

searchesinteger

Vezes que foi buscado.

zero_resultsinteger

Vezes que não achou nada.

clicksinteger

Vezes em que houve clique em um resultado.

conversionsinteger

Compras atribuídas ao termo.

revenue_centsinteger

Receita atribuída, em centavos.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_settings`	`{"error":"insufficient privileges","required":"manage_settings"}`
503	O serviço de estatísticas não está disponível	`{"error":"search analytics unavailable"}`
500	Falha ao calcular	`{"error":"failed to compute summary","detail":"..."}`