Obtenha análises da central de ajuda com a API Notiondesk

A API Notiondesk fornece os dados por trás das páginas de análise da sua central de ajuda: visitantes, visualizações de artigos, tempo na página, países, o que os leitores pesquisam, quais pesquisas não retornam resultados e como os leitores reagem aos seus artigos. Use-a para alimentar uma ferramenta de BI, publicar um relatório semanal no Slack ou encontrar o conteúdo que seus leitores estão procurando.

GET /sites/{site_id}/analytics/{report}

Todos os relatórios precisam do escopo read. Para ler esses números no painel, consulte Como melhorar sua central de ajuda com insights do leitor .

Obtenha um resumo de 30 dias

quick abrange os últimos 30 dias, terminando agora, e não aceita nenhum parâmetro de consulta. articles contabiliza todos os artigos da central de ajuda, incluindo rascunhos. reactions contabiliza a reação mais recente de cada leitor por artigo.

Obtenha um relatório para um intervalo de datas.

overview, search e engagement aceitam um intervalo de datas e um tamanho de bucket:

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/analytics/quick" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "articles": 42,
  "visitors": 25,
  "searches": 9,
  "reactions": 4
}

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/analytics/search?start_date=2026-09-01T00:00:00Z&end_date=2026-10-01T00:00:00Z&date_scale=week&timezone=Europe/Paris" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

Regras para o intervalo:

• As datas usam YYYY-MM-DDTHH:MM[:SS] com um deslocamento opcional. Sem um deslocamento, a data é lida como UTC, não em timezone. Escreva + como %2B na URL ou use Z.

• O período começa em ou após 01/01/2020 e termina no máximo daqui a dois dias.

• No máximo 1.000 baldes. Por exemplo, minute cobre no máximo 16 horas e hour no máximo 41 dias. Use um date_scale mais grosso para intervalos maiores.

• A semana começa na segunda-feira.

Cada relatório compara seu intervalo com o período de mesma duração imediatamente anterior: previous e total_previous descrevem esse período anterior.

Série Contagem

visitors, article_views e searches compartilham uma forma:

{
  "total": 12,
  "total_previous": 8,
  "difference": 4,
  "percentage_difference": 50.0,
  "current": [{"date": "2026-09-14", "count": 7}, {"date": "2026-09-15", "count": 5}],
  "previous": [{"date": "2026-08-20", "count": 8}]
}

• current e previous listam apenas os buckets que contêm dados, do mais antigo para o mais recente.

• O date de um balde é quando ele começa, em timezone: YYYY-MM-DD para day e mais grosso, YYYY-MM-DDTHH:MM para hour e minute.

• percentage_difference é 0.0 quando o total anterior é 0.

overview

search

{
  "searches_without_results": {
    "total": 3,
    "total_previous": 0,
    "difference": 3,
    "percentage_difference": 0.0,
    "queries": [{"query": "refund policy", "searches": 3}]
  }
}

Observação: seu acervo de conteúdo é composto por cada consulta, que representa uma pergunta feita por leitores e que sua central de ajuda não conseguiu responder. searches_without_results.queries

engagement

Um reaction_summary segue seu estilo de reação:

score varia de 0 a 100: a proporção de reações positivas, com uma reação neutra contando metade em emoji. Com o estilo thumbs, os grupos são helpful e not_helpful. Veja Como coletar feedback com reações a artigos .

Lista de limites

{
  "style": "emoji",
  "total": 6,
  "score": 58,
  "groups": [
    {"key": "positive", "count": 3, "percent": 50},
    {"key": "neutral", "count": 1, "percent": 17},
    {"key": "negative", "count": 2, "percent": 33}
  ]
}

• As listas de consulta, top_articles, top_referrers, article_engagements e articles_to_revise, contêm até 50 linhas cada e abrangem apenas o período atual. Uma lista de 50 linhas pode estar incompleta: reduza o intervalo para visualizar todas as linhas.

• Os totais abrangem tudo, não apenas as linhas listadas.

title, , , , e vêm dos navegadores dos visitantes, e qualquer pessoa pode falsificá-los. Evite-os antes de exibi-los e nunca os siga ou tome qualquer ação com base neles sem verificar.urlhostpathnamereferrerquery

Análises e seu plano

O acesso à API requer um plano Enterprise, que inclui análises avançadas, permitindo que cada relatório aceite qualquer intervalo e escala dentro de 1.000 categorias.

Limite de taxa

Além das 120 leituras por minuto da sua chave, os relatórios analíticos contam para um orçamento de 30 solicitações por minuto por central de ajuda , compartilhado por todas as chaves e aplicativos OAuth do seu espaço de trabalho. Uma solicitação feita por meio dela retorna o código 429 rate_limited, e o cabeçalho Retry-After indica quando tentar novamente. Armazene os relatórios em cache em vez de solicitá-los a cada carregamento de página.

Erros

Consulte os erros, limites de taxa e novas tentativas da API Handle Notiondesk .

Perguntas frequentes

O que vem a seguir?

• Exporte o feedback do leitor com a API Notiondesk

• Automatize tarefas comuns da central de ajuda com a API Notiondesk

• Lidar com erros da API Notiondesk, limites de taxa e novas tentativas.