v1Recursos/Listagens publicadas/getObter um resumo de listagens

Obter um resumo de listagens

Status de sincronização de publishers nos locais deste cliente (ou de toda a agência) — um resumo agregado mais um detalhamento por local, insights (% de saúde, distribuição de sincronização, publishers mais fracos, itens priorizados "precisa de atenção") e uma manchete determinística. Limite o escopo com tags. Usa o mesmo rollup da visualização Listagens → Todos os locais.

get/api/v1/listings/summary
listings:read
Parâmetros de consulta
clientIdstringopcional
Limitar aos locais de um cliente.
tagsstringopcional
Nomes de tags de local separados por vírgula — apenas locais com pelo menos uma dessas tags são incluídos.
pageintegeropcional
Página das linhas por local (base 1). Padrão 1.
perPageintegeropcional
Linhas por página (máx. 200). Padrão 50.
withVisibilitybooleanopcional
Defina como true para adicionar os resultados citation e maps de cada linha e os totais de visibility. Desativado por padrão.
Resposta
dataobjectopcional
summaryobjectopcional
Contagens agregadas de todos os locais no escopo.
locationsnumberopcional
Número de locais no escopo.
publishersTotalnumberopcional
Total de vagas de publisher em todos os locais no escopo.
publishersSyncednumberopcional
Desses, atualmente sincronizados.
connectionIssuesnumberopcional
Linhas de conectores nativos (Google/Facebook) com problema de conexão.
duplicatesnumberopcional
Listagens duplicadas detectadas no escopo.
reviewsnumberopcional
Total de avaliações no escopo.
avgRatingnumberopcional
Avaliação média entre os locais que possuem uma.
rowsarray of objectopcional
Uma linha por local no escopo (paginada).
locationIdstringopcional
ID do local.
namestringopcional
Nome do local.
citystringopcional
Cidade do local.
publishersnumberopcional
Vagas de publisher para este local.
syncednumberopcional
Dessas, atualmente sincronizadas.
connectionIssuesnumberopcional
Linhas de conectores nativos com problema de conexão.
duplicatesnumberopcional
Listagens duplicadas detectadas para este local.
reviewsnumberopcional
Total de avaliações deste local.
unrepliednumberopcional
Avaliações aguardando resposta.
avgRatingnumberopcional
Avaliação média deste local.
googleVerifiedbooleanopcional
A listagem do Google está conectada e verificada.
googleConnectedbooleanopcional
O Google está conectado (a verificação pode ainda estar pendente).
tagsarray of stringopcional
Tags internas deste local.
healthobjectopcional
A saúde das listagens deste local, contada sobre as mesmas listagens elegíveis da própria visão geral de Listagens dele.
eligibleintegerobrigatório
Listagens de diretório para as quais o local é elegível: cada site ativo disponível para o país, o plano e o conjunto de publishers dele.
liveintegerobrigatório
Destas, as listagens que estão publicadas.
inFlightintegerobrigatório
Destas, as listagens enviadas que aguardam um resultado (em andamento ou com aprovação pendente).
needsActionintegerobrigatório
Destas, as listagens de diretório cujo status exige que alguém aja.
notLiveYetintegerobrigatório
As listagens elegíveis restantes, ainda não publicadas. Null quando as demais contagens não cabem no total elegível.
consistentbooleanobrigatório
True quando live, inFlight, needsAction e notLiveYet somam eligible.
phasestring (preparing | submitting | settled)obrigatório
Em que ponto está a primeira rodada de envios a diretórios do local: preparing, submitting ou settled.
citationobjectopcional
As listagens deste local na Pesquisa Google: as páginas de listagem publicadas atuais, contadas por resultado. Somente com withVisibility=true.
statestring (none | unchecked | measured)obrigatório
none: nenhuma página publicada elegível. unchecked: há páginas, mas nenhuma tem resultado ainda. measured: pelo menos uma página tem resultado.
totalintegerobrigatório
Páginas de listagem publicadas contadas.
indexedintegerobrigatório
Destas, as páginas exibidas na Pesquisa Google.
notIndexedintegerobrigatório
Destas, as páginas com resultado registrado de não indexada.
pendingintegerobrigatório
Destas, as páginas aguardando um resultado.
notCheckedintegerobrigatório
Destas, as páginas ainda sem resultado utilizável.
latestEvidenceAtstringobrigatório
Quando o resultado de página mais recente foi registrado, ou null.
oldestEvidenceAtstringobrigatório
O mais antigo dos resultados mais recentes das páginas, ou null. Com latestEvidenceAt, o intervalo em que os resultados foram registrados.
mapsobjectopcional
Top 3 no Google Maps para a palavra-chave padrão deste local, a partir de uma varredura armazenada. Somente com withVisibility=true.
statestring (noKeywords | notMeasured | measured)obrigatório
noKeywords: nenhuma palavra-chave rastreada. notMeasured: há palavras-chave rastreadas, mas nenhuma tem varredura medida. measured: existe uma varredura medida.
keywordIdstringobrigatório
O id da palavra-chave rastreada.
keywordstringobrigatório
A palavra-chave rastreada.
keywordCountintegerobrigatório
Número de palavras-chave rastreadas para este local.
reportIdstringobrigatório
O id do relatório armazenado.
yearMonthstringobrigatório
O mês que este ponto cobre, como "YYYY-MM".
measuredintegerobrigatório
Pontos contados com uma resposta medida (ranked ou outside). O denominador de top3.
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.
noDataintegerobrigatório
Pontos contados cuja verificação falhou. Não é uma posição.
withheldPointsintegerobrigatório
Pontos armazenados de uma configuração anterior de palavra-chave ou grade. Exibidos como withheld e não contados.
missingPointsintegerobrigatório
Pontos da grade sem nenhum resultado armazenado.
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.
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.
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.
newerUnmeasuredbooleanobrigatório
True quando uma varredura mais recente da palavra-chave não mediu nada contabilizável, por isso uma varredura anterior é exibida.
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.
healthobjectopcional
Saúde das listagens em todos os locais do escopo, não apenas nesta página. As contagens são somadas; porcentagens nunca são calculadas pela média.
locationsintegerobrigatório
Número de locais no escopo.
eligibleintegerobrigatório
Listagens de diretório para as quais o local é elegível: cada site ativo disponível para o país, o plano e o conjunto de publishers dele.
liveintegerobrigatório
Destas, as listagens que estão publicadas.
inFlightintegerobrigatório
Destas, as listagens enviadas que aguardam um resultado (em andamento ou com aprovação pendente).
needsActionintegerobrigatório
Destas, as listagens de diretório cujo status exige que alguém aja.
notLiveYetintegerobrigatório
As listagens elegíveis restantes, ainda não publicadas. Null quando as demais contagens não cabem no total elegível.
locationsNeedingActionintegerobrigatório
Locais com pelo menos uma listagem de diretório que exige ação.
connectionIssuesintegerobrigatório
Linhas de conectores nativos (Google/Facebook) com problema de conexão.
locationsWithConnectionIssuesintegerobrigatório
Locais com pelo menos um problema de conexão.
duplicatesintegerobrigatório
Listagens duplicadas detectadas no escopo.
locationsWithDuplicatesintegerobrigatório
Locais com pelo menos uma listagem duplicada detectada.
preparingintegerobrigatório
Locais novos cujos primeiros envios estão sendo preparados.
submittingintegerobrigatório
Locais novos cujos primeiros envios estão sendo enviados.
visibilityobjectopcional
Totais de visibilidade de todos os locais do escopo, não apenas desta página. Somente com withVisibility=true.
citationobjectobrigatório
Listagens na Pesquisa Google, somadas nos locais com pelo menos uma página de listagem publicada.
totalintegerobrigatório
Páginas de listagem publicadas contadas.
indexedintegerobrigatório
Destas, as páginas exibidas na Pesquisa Google.
notIndexedintegerobrigatório
Destas, as páginas com resultado registrado de não indexada.
pendingintegerobrigatório
Destas, as páginas aguardando um resultado.
notCheckedintegerobrigatório
Destas, as páginas ainda sem resultado utilizável.
locationsobjectobrigatório
Locais por estado de citação.
oldestEvidenceAtstringobrigatório
O mais antigo dos resultados mais recentes das páginas, ou null. Com latestEvidenceAt, o intervalo em que os resultados foram registrados.
latestEvidenceAtstringobrigatório
Quando o resultado de página mais recente foi registrado, ou null.
mapsobjectobrigatório
Top 3 no Google Maps, somado a partir da própria varredura de cada local medido.
measuredintegerobrigatório
Pontos contados com uma resposta medida (ranked ou outside). O denominador de top3.
top3integerobrigatório
Pontos medidos em que você ficou entre os 3 primeiros.
locationsobjectobrigatório
Locais por estado do Maps.
completedintegerobrigatório
Locais medidos cuja data de varredura é uma coleta verificada da grade completa, e não uma data de relatório registrada.
scannedFromstringobrigatório
Início ou fim do intervalo de datas de coleta verificadas (completedAt) nos locais medidos. Null quando não há nenhuma.
scannedTostringobrigatório
Início ou fim do intervalo de datas de coleta verificadas (completedAt) nos locais medidos. Null quando não há nenhuma.
reportedFromstringobrigatório
Início ou fim do intervalo de datas de relatório registradas (generatedAt) dos locais medidos sem coleta verificada. Null quando não há nenhuma. Nunca é combinado com o intervalo de varredura.
reportedTostringobrigatório
Início ou fim do intervalo de datas de relatório registradas (generatedAt) dos locais medidos sem coleta verificada. Null quando não há nenhuma. Nunca é combinado com o intervalo de varredura.
insightsobjectopcional
Insights derivados calculados a partir das linhas acima.
healthnumberopcional
publishersSynced / publishersTotal, em porcentagem.
distributionobjectopcional
Locais agrupados por taxa de sincronização (fullySynced 100%, healthy 90-99%, atRisk <90%).
fullySyncednumberopcional
Locais com 100% de sincronização.
healthynumberopcional
Locais com 90-99% de sincronização.
atRisknumberopcional
Locais abaixo de 90% de sincronização.
weakestarray of objectopcional
Publishers com menor cobertura no escopo.
idstringopcional
ID do publisher.
namestringopcional
Nome do publisher.
totalnumberopcional
Locais que possuem este publisher.
syncednumberopcional
Desses, sincronizados.
requiresActionnumberopcional
Desses, que precisam de ação.
notConnectednumberopcional
Desses, não conectados.
pctnumberopcional
Percentual sincronizado, arredondado.
directoriesarray of objectopcional
Tabela completa de cobertura por publisher.
idstringopcional
ID do publisher.
namestringopcional
Nome do publisher.
totalnumberopcional
Locais que possuem este publisher.
syncednumberopcional
Desses, sincronizados.
requiresActionnumberopcional
Desses, que precisam de ação.
notConnectednumberopcional
Desses, não conectados.
pctnumberopcional
Percentual sincronizado, arredondado.
attentionarray of objectopcional
Cartões priorizados de "precisa de atenção".
nnumberopcional
Quantidade que este cartão representa.
titlestringopcional
Título do cartão.
substringopcional
Subtítulo do cartão.
tonestring (amber | blue | rose | zinc)opcional
Tom visual deste cartão.
filterstring (issues | duplicates | under80 | unverified | notconnected)opcional
Chave de filtro correspondente na tabela de locais.
headlinestringopcional
Uma manchete determinística de uma linha sobre a saúde do escopo.
fixFirstarray of objectopcional
Correções priorizadas.
textstringopcional
Descrição da correção.
impactstring (High | Med | Low)opcional
Impacto estimado desta correção.
filterstring (issues | duplicates | under80 | unverified | notconnected)opcional
Chave de filtro correspondente na tabela de locais.
totalnumberopcional
Total de locais correspondentes (para paginação), independente de perPage.
pagenumberopcional
Página atual (base 1).
perPagenumberopcional
Linhas por página.
Erros
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/listings/summary
Sua chave de API
clientId
tags
page
perPage
withVisibility
{
  "data": {
    "summary": {
      "locations": 12,
      "publishersTotal": 96,
      "publishersSynced": 81,
      "connectionIssues": 3,
      "duplicates": 2,
      "reviews": 340,
      "avgRating": 4.6
    },
    "rows": [
      {
        "locationId": "loc_456",
        "name": "Acme Dental — Downtown",
        "city": "Austin",
        "publishers": 8,
        "synced": 7,
        "connectionIssues": 0,
        "duplicates": 0,
        "reviews": 26,
        "unreplied": 2,
        "avgRating": 4.8,
        "googleVerified": true,
        "googleConnected": true,
        "facebookConnected": true,
        "tags": [
          "vip"
        ]
      }
    ],
    "insights": {
      "health": 84,
      "distribution": {
        "fullySynced": 9,
        "healthy": 2,
        "atRisk": 1
      },
      "weakest": [
        {
          "locationId": "loc_789",
          "name": "Acme Dental — Eastside",
          "health": 40
        }
      ],
      "directories": [
        {
          "id": "google",
          "name": "Google Maps",
          "total": 12,
          "synced": 11,
          "requiresAction": 0,
          "notConnected": 1,
          "pct": 92
        }
      ],
      "attention": [
        {
          "n": 1,
          "title": "1 location under 90% synced",
          "sub": "Listings not fully propagated",
          "tone": "amber",
          "filter": "under80"
        }
      ],
      "headline": "84% listing health — 1 location under 90% synced needs attention.",
      "fixFirst": [
        {
          "text": "Reconnect 1 location's listing sync.",
          "impact": "Med"
        }
      ]
    },
    "total": 12,
    "page": 1,
    "perPage": 50
  }
}

Guias que usam este endpoint