Synupv1
Criar chave
v1Recursos/AEO

AEO

Acompanhe a visibilidade de um local em motores de resposta de IA (ChatGPT, Gemini, Perplexity): com que frequência é mencionado, como se classifica em relação aos concorrentes, e o que está limitando sua pontuação.

Retorna o relatório de visibilidade em IA mais recente de um local: pontuações gerais e por motor, a matriz de palavra-chave/prompt, comparações de lacunas e classificação em relação aos concorrentes, cobertura de citações, sentimento e correções recomendadas. A geração do relatório é assíncrona — este também é o alvo de consulta para POST /api/v1/aeo/reports/enqueue: continue chamando este endpoint e observe o campo generating até que volte a false e generatedAt seja atualizado. Passe prompt para detalhar um único prompt monitorado em vez do relatório completo.

Obter o relatório AEO de um local

get/api/v1/aeo/reports
aeo:read
Parâmetros de consulta
locationIdstringobrigatório
O local a ser consultado.
clientIdstringopcional
O cliente do local.
promptstringopcional
Detalha um único prompt monitorado (correspondência sem diferenciar maiúsculas/minúsculas) em vez de retornar o relatório completo. Retorna células null se o prompt não estiver na matriz deste local.
Resposta
dataobjectopcional
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/aeo/reports
Sua chave de API
locationId *
clientId
prompt
{
  "data": {
    "generatedAt": "2026-02-01T06:00:00.000Z",
    "generating": false,
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "visibility": {
      "overall": 62,
      "label": "GOOD",
      "message": "Your business shows up for most of the prompts you're tracking.",
      "engines": {
        "ChatGPT": {
          "score": 68,
          "comparisonPct": 12,
          "configured": true
        },
        "Gemini": {
          "score": 56,
          "comparisonPct": -4,
          "configured": true
        },
        "Perplexity": {
          "score": null,
          "comparisonPct": null,
          "configured": false
        }
      }
    },
    "metrics": {
      "visibility": {
        "value": 62,
        "delta": 5
      },
      "mentionRate": {
        "value": 71,
        "delta": 3
      },
      "avgPosition": {
        "value": 2.1,
        "delta": -0.4
      },
      "promptsCovered": {
        "value": 8,
        "total": 10
      },
      "sourcesCited": {
        "value": 14,
        "delta": 2
      }
    },
    "keywordMap": {
      "ChatGPT": [
        {
          "keyword": "best dentist austin",
          "percentage": 82,
          "dataSources": [
            {
              "name": "Google Business Profile"
            }
          ]
        }
      ],
      "Gemini": [
        {
          "keyword": "emergency dentist austin",
          "percentage": 54,
          "dataSources": []
        }
      ],
      "Perplexity": []
    },
    "matrix": [
      {
        "keyword": "best dentist austin",
        "cells": {
          "ChatGPT": {
            "score": 82,
            "mentioned": true,
            "rank": 1,
            "answerExcerpt": "Acme Dental — Downtown is highly rated for..."
          },
          "Gemini": {
            "score": 54,
            "mentioned": true,
            "rank": 3,
            "answerExcerpt": null
          },
          "Perplexity": null
        },
        "best": 82
      }
    ],
    "gap": [
      {
        "business": "Acme Dental — Downtown",
        "isYou": true,
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "comparisonPct": null
      },
      {
        "business": "Smile Bright Dental",
        "isYou": false,
        "overall": 71,
        "chatgpt": 74,
        "gemini": 68,
        "perplexity": null,
        "comparisonPct": 9
      }
    ],
    "ranking": {
      "All": {
        "primary": {
          "good": 6,
          "neutral": 2,
          "bad": 2
        },
        "competitors": []
      },
      "ChatGPT": {
        "primary": {
          "good": 7,
          "neutral": 1,
          "bad": 2
        },
        "competitors": []
      },
      "Gemini": {
        "primary": {
          "good": 5,
          "neutral": 3,
          "bad": 2
        },
        "competitors": []
      },
      "Perplexity": {
        "primary": {
          "good": 0,
          "neutral": 0,
          "bad": 0
        },
        "competitors": []
      }
    },
    "radar": {
      "ChatGPT": {
        "relevance": 78,
        "reviews": 88,
        "engagement": 65,
        "freshness": 74,
        "citations": 81
      },
      "Gemini": {
        "relevance": 70,
        "reviews": 80,
        "engagement": 75,
        "freshness": 85,
        "citations": 65
      },
      "Perplexity": {
        "relevance": 0,
        "reviews": 0,
        "engagement": 0,
        "freshness": 0,
        "citations": 0
      }
    },
    "factors": [
      {
        "key": "citations",
        "label": "Citations",
        "value": 81,
        "detail": "Cited by 14 of 20 tracked sources across configured engines.",
        "action": {
          "label": "Fix missing citations",
          "target": "citations"
        }
      }
    ],
    "citations": {
      "summary": {
        "totalSources": 20,
        "active": 14,
        "detected": 4,
        "missing": 2,
        "missingDirectories": [
          "Yelp"
        ]
      },
      "byEngine": {
        "ChatGPT": [
          {
            "name": "Google Business Profile",
            "status": "active"
          }
        ],
        "Gemini": [],
        "Perplexity": []
      }
    },
    "sentiment": {
      "positive": 62,
      "neutral": 30,
      "negative": 8,
      "mentions": []
    },
    "attention": [
      {
        "text": "Bing Places is missing your current hours.",
        "tone": "warn"
      }
    ],
    "recommendations": [
      {
        "id": "rec_reviews_1",
        "kind": "opportunity",
        "priority": "high",
        "title": "Add more customer reviews mentioning services",
        "detail": "Reviews that name specific services improve how often engines cite you for those prompts.",
        "action": {
          "label": "Request reviews",
          "target": "reviews"
        }
      }
    ],
    "history": [
      {
        "yearMonth": "2026-01",
        "overall": 57,
        "chatgpt": 61,
        "gemini": 53,
        "perplexity": null,
        "sources": 12
      },
      {
        "yearMonth": "2026-02",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "sources": 14
      }
    ],
    "competitorHistory": [
      {
        "name": "Smile Bright Dental",
        "points": [
          {
            "yearMonth": "2026-01",
            "overall": 65
          },
          {
            "yearMonth": "2026-02",
            "overall": 71
          }
        ]
      }
    ]
  }
}
v1Recursos/AEO/postEnfileirar a geração de relatório AEO

Inicia uma geração em segundo plano de um novo relatório AEO para um local. A geração do relatório executa múltiplas chamadas de LLM por motor/prompt e nunca é executada de forma síncrona durante a requisição — esta chamada enfileira o job e retorna imediatamente. Não há um recurso separado de id de job ou status: consulte GET /api/v1/aeo/reports para o mesmo local e observe o campo generating até que volte a false. Não disponível para locais anteriores ao cache legado de locais do Synup (locais somente nativos).

Enfileirar a geração de relatório AEO

post/api/v1/aeo/reports/enqueue
aeo:write
Corpo da solicitação
locationIdstringobrigatório
O local para o qual gerar um relatório.
clientIdstringopcional
O cliente do local.
forcebooleanopcional
Quando true, inicia uma nova geração mesmo que um relatório já tenha sido gerado neste mês.
Resposta
dataobjectopcional
enqueuedbooleanopcional
Sempre true — o job de geração foi enfileirado.
forcebooleanopcional
Repete a flag force da solicitação.
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.
post/api/v1/aeo/reports/enqueue
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "enqueued": true,
    "force": false
  }
}
v1Recursos/AEO/getObter o resumo AEO de todos os locais

Retorna o resumo do relatório AEO mais recente por local, opcionalmente restrito a um cliente e/ou tags de local, além de dados de tendência e correções sistêmicas em todo o portfólio. Locais sem relatório ainda mostram pontuações null.

Obter o resumo AEO de todos os locais

get/api/v1/aeo/rollup
aeo:read
Parâmetros de consulta
clientIdstringopcional
Restringe os resultados a um cliente. Quando sua chave está limitada a clientes específicos, isso é obrigatório.
tagsstringopcional
Lista de nomes de tags de local separados por vírgula. Somente locais com pelo menos uma dessas tags são incluídos.
Resposta
dataobjectopcional
rowsarray of objectopcional
Uma linha por local em escopo.
locationIdstringopcional
Identificador único do local.
namestringopcional
O nome comercial do local.
citystringopcional
Cidade, ou null.
overallnumberopcional
Pontuação geral de visibilidade em IA mais recente (0-100), ou null se nunca gerada.
chatgptnumberopcional
Pontuação do ChatGPT mais recente, ou null.
gemininumberopcional
Pontuação do Gemini mais recente, ou null.
perplexitynumberopcional
Pontuação do Perplexity mais recente, ou null.
generatedAtstringopcional
Quando o relatório mais recente foi gerado, como timestamp ISO 8601, ou null se nunca gerado.
yearMonthstringopcional
Mês do relatório mais recente (YYYY-MM), ou null.
tagsarray of stringopcional
As tags internas do local.
historyarray of numberopcional
Histórico de pontuação geral para este local, cronológico, apenas valores não nulos.
deltanumberopcional
Variação na pontuação geral em relação ao relatório anterior, ou null no primeiro relatório ou se não houver mês anterior.
topIssueobjectopcional
O fator de visibilidade mais fraco deste local, ou null se ainda não tiver relatório.
labelstringopcional
tonestring (good | warn | bad)opcional
configuredEnginesarray of string (ChatGPT | Gemini | Perplexity)opcional
Motores de IA para os quais esta agência tem uma chave de API configurada.
portfolioHistoryarray of objectopcional
Pontuação geral média entre os locais em escopo, por mês.
yearMonthstringopcional
Mês no formato YYYY-MM.
avgnumberopcional
Pontuação geral média entre os locais que reportaram naquele mês.
locationsnumberopcional
Número de locais com um relatório naquele mês (o denominador da média).
systemicFixesarray of objectopcional
Fraquezas entre locais compartilhadas por vários locais, cada uma com uma única correção em lote, classificadas por alcance.
factorstringopcional
Identificador legível por máquina do fator.
labelstringopcional
Nome legível do fator.
detailstringopcional
Explicação da fraqueza sistêmica.
targetstring (listings | citations | reviews | posts | competitors | prompts)opcional
Para qual parte do produto a correção direciona.
countnumberopcional
Número de locais afetados.
pctnumberopcional
Percentual de locais que reportaram afetados.
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/aeo/rollup
Sua chave de API
clientId
tags
{
  "data": {
    "rows": [
      {
        "locationId": "cm_loc_1",
        "name": "Acme Dental — Downtown",
        "city": "Austin",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "generatedAt": "2026-02-01T06:00:00.000Z",
        "yearMonth": "2026-02",
        "tags": [
          "priority"
        ],
        "history": [
          57,
          62
        ],
        "delta": 5,
        "topIssue": null
      }
    ],
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "portfolioHistory": [
      {
        "yearMonth": "2026-01",
        "avg": 57,
        "locations": 5
      },
      {
        "yearMonth": "2026-02",
        "avg": 62,
        "locations": 5
      }
    ],
    "systemicFixes": [
      {
        "factor": "citations",
        "label": "Citations",
        "detail": "6 locations are missing citations on Yelp.",
        "target": "citations",
        "count": 6,
        "pct": 30
      }
    ]
  }
}