Synup
Criar chave
v1Recursos/Listagens publicadas/getObter Share of Voice

Obter Share of Voice

Sua participação no Grid Rank em relação a concorrentes nomeados, suas palavras-chave de melhor desempenho classificadas pela participação top-3 mais recente, e uma tendência mensal de posição média na janela — para um local.

get/api/v1/seo/share-of-voice
seo:read
Parâmetros de consulta
locationIdstringobrigatório
O local a consultar. Procure com GET /api/v1/locations.
clientIdstringopcional
O cliente do local. Necessário apenas para desambiguar quando sua chave é limitada a clientes específicos.
fromstringopcional
Início da janela (data ISO). Padrão: 30 dias atrás.
tostringopcional
Fim da janela (data ISO). Padrão: agora.
keywordIdstringopcional
Um id de palavra-chave rastreada de maps.keywords para ler o Top 3 no Google Maps. Omita para usar a palavra-chave mais recente com uma varredura medida.
Resposta
dataobjectopcional
comparisonobjectopcional
Você em relação a concorrentes nomeados pela participação top-3 do grid.
availablebooleanopcional
Se este local tem dados de grid-rank para calcular o Share of Voice.
rowsarray of objectopcional
Uma linha por empresa na comparação — você e seus concorrentes nomeados.
namestringopcional
O nome da empresa, ou o nome do seu próprio cliente na sua própria linha.
top3Pctnumberopcional
Percentual de palavras-chave rastreadas em que esta empresa está entre as 3 primeiras posições (0–100), ou null se não houver dados suficientes.
isYoubooleanopcional
True na linha do seu próprio local. Omitido (nunca false) nas linhas de concorrentes.
keywordsobjectopcional
As palavras-chave deste local, classificadas pela participação top-3 mais recente.
availablebooleanopcional
Se este local tem dados de grid-rank para calcular o Share of Voice.
rowsarray of objectopcional
Uma linha por palavra-chave rastreada.
keywordstringopcional
A palavra-chave rastreada.
top3Pctnumberopcional
Percentual de palavras-chave rastreadas em que esta empresa está entre as 3 primeiras posições (0–100), ou null se não houver dados suficientes.
avgRanknumberopcional
Posição média no período, ou null se não houver dados suficientes.
performanceobjectopcional
Tendência mensal de posição média por palavra-chave, limitada por from/to.
availablebooleanopcional
Se este local tem dados de grid-rank para calcular o Share of Voice.
seriesarray of objectopcional
Uma série por palavra-chave rastreada.
keywordstringopcional
A palavra-chave rastreada.
pointsarray of objectopcional
Pontos de dados de posição média mensal para esta palavra-chave.
mapsobjectopcional
Top 3 no Google Maps para uma palavra-chave, a partir de uma varredura de grade armazenada.
availablebooleanobrigatório
False quando sua chave não pode ler este local.
keywordsarray of objectobrigatório
As palavras-chave rastreadas ativas do local, da mais recente para a mais antiga.
idstringobrigatório
O id da palavra-chave rastreada.
keywordstringobrigatório
A palavra-chave rastreada.
measuredbooleanobrigatório
True quando existe uma varredura armazenada com pelo menos um ponto medido para esta palavra-chave.
selectedKeywordIdstringobrigatório
A palavra-chave a que se referem todos os números de maps. Null quando o local não rastreia palavras-chave.
selectionstring (requested | default)obrigatório
requested: você informou a palavra-chave com keywordId. default: a palavra-chave mais recente com uma varredura medida ou, se não houver, a mais recente.
reportobjectobrigatório
A varredura mais recente da palavra-chave selecionada com um ponto medido. Null significa nenhuma varredura medida, nunca 0%.
idstringobrigatório
O id do relatório armazenado.
keywordIdstringobrigatório
O id da palavra-chave rastreada.
keywordstringobrigatório
A palavra-chave rastreada.
yearMonthstringobrigatório
O mês que este ponto cobre, como "YYYY-MM".
gridSizeintegerobrigatório
O comprimento do lado configurado da grade quando foi varrida. points contém os pontos reais.
completedAtstringobrigatório
Quando foi concluída a coleta da grade completa por trás exatamente destes resultados. Null, a menos que isso esteja comprovado.
generatedAtstringobrigatório
A data registrada do relatório, definida quando ele foi finalizado pela primeira vez. Não é um horário de coleta, de última atualização nem uma verificação em tempo real.
evidencestring (proven | unverified)obrigatório
proven: cada ponto contado corresponde à palavra-chave e à grade atuais. unverified: uma varredura legada cuja palavra-chave e grade não podem ser confirmadas.
pointsarray of objectobrigatório
Cada ponto de grade armazenado, em ordem de linha e coluna, com seu estado.
missingPointsintegerobrigatório
Pontos da grade sem nenhum resultado armazenado.
withheldPointsintegerobrigatório
Pontos armazenados de uma configuração anterior de palavra-chave ou grade. Exibidos como withheld e não contados.
countedintegerobrigatório
Pontos armazenados que este local conta, sem incluir os pontos water e excluded.
measuredintegerobrigatório
Pontos contados com uma resposta medida (ranked ou outside). O denominador de top3.
noDataintegerobrigatório
Pontos contados cuja verificação falhou. Não é uma posição.
top3integerobrigatório
Pontos medidos em que você ficou entre os 3 primeiros.
outsideintegerobrigatório
Pontos medidos em que você não estava no top 20 rastreado.
top3Pctnumberobrigatório
Percentual de palavras-chave rastreadas em que esta empresa está entre as 3 primeiras posições (0–100), ou null se não houver dados suficientes.
avgRanknumberobrigatório
Posição média nos pontos medidos, contando outside como 21. Null quando nada foi medido.
bestRankintegerobrigatório
Melhor posição medida, de 1 a 20. Null quando todos os pontos medidos são outside.
businessPointobjectobrigatório
O ponto amostrado mais próximo das coordenadas do próprio local. Um ponto de pesquisa, não o endereço em si. Null quando o local não tem coordenadas.
newerUnmeasuredobjectobrigatório
Uma varredura mais recente da palavra-chave que não mediu nada contabilizável, informada ao lado de report e não no lugar dele. Null quando não há nenhuma.
yearMonthstringobrigatório
O mês que este ponto cobre, como "YYYY-MM".
generatedAtstringobrigatório
A data registrada do relatório, definida quando ele foi finalizado pela primeira vez. Não é um horário de coleta, de última atualização nem uma verificação em tempo real.
competitorsarray of objectobrigatório
Você e os principais concorrentes, contados sobre os pontos medidos do relatório. Vazio sem relatório.
idstringobrigatório
Um id estável da empresa: id: seguido do id de lugar do Google ou, se não houver, o nome mais o endereço. "you" na sua própria linha.
namestringobrigatório
O nome da empresa conforme registrado. Pode estar vazio, e está vazio na sua própria linha.
addressstringobrigatório
O endereço conforme registrado, quando a varredura capturou um. Diferencia filiais com o mesmo nome.
isYoubooleanobrigatório
True na linha do seu próprio local. Omitido (nunca false) nas linhas de concorrentes.
top3Spotsintegerobrigatório
Pontos medidos em que esta empresa ficou entre as 3 primeiras. As empresas compartilham pontos, então as linhas não somam o total.
scanInProgressbooleanobrigatório
True enquanto uma varredura de grade está em execução para este local. Vale para o local inteiro: não indica quais palavras-chave a varredura cobre.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/seo/share-of-voice
Sua chave de API
locationId *
clientId
from
to
keywordId
{
  "data": {
    "comparison": {
      "available": true,
      "rows": [
        {
          "name": "Acme Dental — Downtown",
          "top3Pct": 62,
          "isYou": true
        },
        {
          "name": "Bright Smiles Dental",
          "top3Pct": 74
        }
      ]
    },
    "keywords": {
      "available": true,
      "rows": [
        {
          "keyword": "dentist near me",
          "top3Pct": 62,
          "avgRank": 3.2
        }
      ]
    },
    "performance": {
      "available": true,
      "series": [
        {
          "keyword": "dentist near me",
          "points": [
            {
              "yearMonth": "2026-01",
              "avgRank": 3.6
            },
            {
              "yearMonth": "2026-02",
              "avgRank": 3.2
            }
          ]
        }
      ]
    }
  }
}

Guias que usam este endpoint