Synupv1
Criar chave
v1Recursos/Listagens publicadas

Listagens publicadas

Consulte o status de sincronização de listagens de um local nos diretórios.

Retorna o status de sincronização entre publishers, o status do perfil do Google Business e oportunidades de melhoria para um local.

Obter a listagem de um local

get/api/v1/listings
listings:read
Parâmetros de consulta
locationIdstringobrigatório
O local a ser consultado. Obrigatório. Procure com GET /api/v1/locations.
clientIdstringopcional
O cliente do local. Necessário apenas para desambiguar quando sua chave está limitada a clientes específicos.
Resposta
dataobjectopcional
statsobjectopcional
Números resumidos de todos os publishers deste local.
publishersnumberopcional
Número total de publishers monitorados.
syncednumberopcional
Número de publishers atualmente sincronizados.
notConnectednumberopcional
Número de publishers ainda não conectados.
googleVerifiedLocationsnumberopcional
Número de locais verificados pelo Google.
duplicatesnumberopcional
Número de listagens duplicadas detectadas.
connectionIssuesnumberopcional
Número de publishers com problema de conexão.
requiresActionnumberopcional
Número de publishers que exigem uma ação.
publishersarray of objectopcional
Status de sincronização por publisher.
publisherIdstringopcional
Identificador do diretório/publisher.
publisherNamestringopcional
Nome de exibição do publisher.
statusstring (synced | in_progress | failed | requires_action | not_connected | expired | suspended | pending_approval | inaccessible | credentials_invalidated | not_available)opcional
Um de: synced, in_progress, failed, requires_action, not_connected, expired, suspended, pending_approval, inaccessible, credentials_invalidated, not_available.
liveLinksnumberopcional
Número de links ativos encontrados para este publisher, ou null.
gbpobjectopcional
Resumo do perfil do Google Business, quando conectado.
connectedbooleanopcional
Se um perfil do Google Business está conectado.
scorenumberopcional
Pontuação de completude do perfil, de 0 a 100, ou null.
donearray of stringopcional
Itens de melhoria do perfil já concluídos.
todoarray of stringopcional
Itens de melhoria do perfil pendentes.
opportunitiesarray of objectopcional
Melhorias sugeridas, cada uma com uma mensagem curta e um tom.
textstringopcional
tonestring (amber | rose | blue | zinc)opcional
aiobjectopcional
Um breve título gerado por IA e até 3 correções priorizadas para este local, ou null.
headlinestringopcional
Resumo de uma frase sobre a saúde das listagens deste local.
fixFirstarray of objectopcional
Até 3 ações sugeridas, classificadas por impacto.
textstringopcional
impactstring (High | Med | Low)opcional
noticestringopcional
Um aviso legível sobre os dados de listagens deste local, ou null.
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.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/listings
Sua chave de API
locationId *
clientId
{
  "data": {
    "stats": {
      "publishers": 42,
      "synced": 38,
      "notConnected": 2,
      "googleVerifiedLocations": 1,
      "duplicates": 0,
      "connectionIssues": 1,
      "requiresAction": 1
    },
    "publishers": [
      {
        "publisherId": "google",
        "publisherName": "Google",
        "status": "synced",
        "liveLinks": 1
      }
    ],
    "gbp": {
      "connected": true,
      "score": 82,
      "done": [
        "Business name",
        "Address"
      ],
      "todo": [
        "Add photos"
      ]
    },
    "opportunities": [
      {
        "text": "Add more photos to your Google profile",
        "tone": "amber"
      }
    ],
    "ai": {
      "headline": "90% synced — 1 listing needs action.",
      "fixFirst": [
        {
          "text": "Reconnect 1 listing needing action.",
          "impact": "High"
        }
      ]
    },
    "notice": null
  }
}
v1Recursos/Listagens publicadas/getObter 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.

Obter um resumo de listagens

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.
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.
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
{
  "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
  }
}
v1Recursos/Listagens publicadas/getObter 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.

Obter Share of Voice

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.
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.
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
{
  "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
            }
          ]
        }
      ]
    }
  }
}
v1Recursos/Listagens publicadas/getObter Índice de Citações

Quantos diretórios indexam este local, atual em relação a um período anterior.

Obter Índice de Citações

get/api/v1/seo/citation-index
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.
Resposta
dataobjectopcional
availablebooleanopcional
Se já existe um snapshot do índice de citações para este local.
currentobjectopcional
O snapshot mais recente na ou antes do fim da janela.
percentagenumberopcional
Percentual de listagens atualmente indexadas (0–100), ou null.
listingsnumberopcional
Total de listagens ativas contabilizadas neste snapshot, ou null.
indexednumberopcional
Dessas, quantas estão indexadas, ou null.
previousobjectopcional
O snapshot mais recente na ou antes do início da janela, para comparação.
percentagenumberopcional
Percentual de listagens atualmente indexadas (0–100), ou null.
listingsnumberopcional
Total de listagens ativas contabilizadas neste snapshot, ou null.
indexednumberopcional
Dessas, quantas estão indexadas, ou null.
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/citation-index
Sua chave de API
locationId *
clientId
from
to
{
  "data": {
    "available": true,
    "current": {
      "percentage": 90.48,
      "listings": 42,
      "indexed": 38
    },
    "previous": {
      "percentage": 83.33,
      "listings": 42,
      "indexed": 35
    }
  }
}