Calcular a avaliação média ponderada de um produto
Transforme uma distribuição de avaliações de cinco estrelas nos dois números mais úteis para consumidores e equipes de e-commerce: a média ponderada e o total de reviews.
Executar grátis
Informe a quantidade registrada em cada nível, de uma a cinco estrelas. A calculadora multiplica cada quantidade pelo valor da estrela, soma os resultados ponderados e divide pelo total completo. Ela também soma todas as faixas para informar quantos reviews estão representados. O cálculo é determinístico, não exige identificadores do produto e rejeita uma distribuição vazia para evitar uma nota zero enganosa.
Informe a distribuição completa das avaliações
Comece pelas cinco contagens fornecidas por sua loja, exportação de marketplace, plataforma de reviews ou banco de dados de relatórios. Coloque o número de avaliações de uma estrela no primeiro campo e faça o mesmo para duas, três, quatro e cinco estrelas. As quantidades precisam ser números inteiros iguais ou superiores a zero, pois representam reviews reais, e não percentuais ou uma nota já calculada. Preencha com zero as faixas sem avaliações; não as omita. O cálculo atende tanto a um item novo com um único review quanto a um produto consolidado com milhões, desde que cada quantidade permaneça no intervalo de inteiros seguros. Use dados do mesmo produto, escopo de variações, canal e momento de apuração. Misturar uma contagem histórica de cinco estrelas com uma contagem mensal de uma estrela gera um número matematicamente válido, mas sem uma população real correspondente. Se a fonte fornecer apenas percentuais, procure obter as contagens originais, porque percentuais arredondados podem não reconstruir o total verdadeiro. Quando os cinco números compatíveis estiverem prontos, envie-os juntos como uma única distribuição.
Entenda como funciona a ponderação
Uma média simples das cinco quantidades responderia à pergunta errada. A calculadora atribui a cada faixa seu valor em estrelas: cada review de uma estrela contribui com um ponto, cada review de duas estrelas contribui com dois pontos e assim por diante, até cinco pontos para cada avaliação de cinco estrelas. Em seguida, soma essas contribuições para obter a pontuação ponderada e divide pelo total de reviews em todas as faixas. Por exemplo, dez avaliações de cinco estrelas influenciam o resultado cinco vezes mais do que dez avaliações de uma estrela, pois geram cinquenta pontos em vez de dez. A média retornada é arredondada para no máximo seis casas decimais, mantendo a saída estável e mais precisa do que a exibição comum de uma loja. O total é retornado separadamente e nunca deduzido da média. Se as cinco contagens forem zero, não existe população e, portanto, não há média ponderada definida. Nesse caso, a capacidade informa uma entrada inválida em vez de criar uma nota zero que poderia ser confundida com a opinião real dos consumidores.
Use o resultado de maneira consistente
A média calculada pode alimentar controles de qualidade do catálogo, painéis internos, enriquecimento de feeds, conciliação com marketplaces e regras de exibição. Defina separadamente como sua loja deve apresentá-la: é possível mostrar uma ou duas casas decimais ou usar o preenchimento gráfico de estrelas, mantendo o valor mais preciso para comparações. Preserve sempre o total de reviews ao lado da média, pois a confiança e o significado comercial são muito diferentes entre uma nota baseada em duas avaliações e a mesma nota baseada em vinte mil. Ao comparar canais, calcule cada canal usando suas próprias cinco faixas. Para obter uma nota geral, some primeiro as contagens correspondentes e execute a distribuição combinada; calcular a média das médias pode dar peso excessivo a um canal com poucos reviews. Em pipelines automatizados, guarde o horário da fonte e a chave do produto com o resultado, embora eles não sejam entradas deste cálculo. O uso no navegador é gratuito, enquanto cada chamada de API custa US$ 0,002. A mesma aritmética determinística atende aos dois caminhos, portanto as mesmas contagens sempre geram os mesmos números.
Casos de uso
Montar um resumo na vitrine
Converta as cinco faixas armazenadas para um produto na média e no total exibidos ao lado do nome.
Conferir relatórios de marketplaces
Recalcule uma nota usando contagens exportadas e identifique resumos incompatíveis com a distribuição informada.
Combinar canais de reviews
Some as faixas equivalentes de vários canais e calcule uma nota corretamente ponderada para toda a população.
Perguntas frequentes
Quanto custa o cálculo?
A execução é gratuita no navegador nesta página. Cada solicitação de API custa US$ 0,002.
Por que não posso enviar cinco contagens iguais a zero?
Uma população sem reviews não possui média definida. Retornar zero sugeriria, incorretamente, que os consumidores deram uma nota de zero estrela.
Uma contagem de estrelas pode ter casas decimais?
Não. As contagens representam reviews individuais e precisam ser números inteiros não negativos.
Como a média é arredondada?
O resultado é arredondado para no máximo seis casas decimais, garantindo estabilidade e precisão. Sua loja pode adotar outro arredondamento na exibição.
Como combinar avaliações de várias lojas?
Some todas as contagens de uma estrela, depois as de duas e assim por diante. Calcule a nota usando essas cinco faixas combinadas, sem tirar a média das notas das lojas.
Para desenvolvedores — acesso via API
Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.
Endpoint
Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.
Chame do seu código
curl -X POST https://api.kit.forhosting.com/ecom/review-rating-average \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"one_star_count":4,"two_star_count":6,"three_star_count":10,"four_star_count":30,"five_star_count":50}'const res = await fetch("https://api.kit.forhosting.com/ecom/review-rating-average", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"one_star_count": 4,
"two_star_count": 6,
"three_star_count": 10,
"four_star_count": 30,
"five_star_count": 50
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/ecom/review-rating-average",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"one_star_count": 4,
"two_star_count": 6,
"three_star_count": 10,
"four_star_count": 30,
"five_star_count": 50
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/ecom/review-rating-average", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"one_star_count":4,"two_star_count":6,"three_star_count":10,"four_star_count":30,"five_star_count":50}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"one_star_count":4,"two_star_count":6,"three_star_count":10,"four_star_count":30,"five_star_count":50}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/ecom/review-rating-average", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Exemplo de requisição
{
"one_star_count": 4,
"two_star_count": 6,
"three_star_count": 10,
"four_star_count": 30,
"five_star_count": 50
}Exemplo de resposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "ecom.review_rating_average",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.
Preço
Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.
Erros
| HTTP | Código | O que significa |
|---|---|---|
401 | unauthorized | Token ausente ou inválido. Confira o header Authorization. |
402 | insufficient_balance | Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo. |
404 | unknown_type | Esse tipo de tarefa não existe. Confira o campo type no catálogo. |
429 | rate_limited | Muitas requisições em pouco tempo. Espere um instante e tente de novo. |