Diagnóstico grátis no ChatGPT e nas AI Overviews →

Fazer diagnóstico

A API devolve em JSON os dados do seu painel: a visibilidade por semana, as perguntas monitorizadas, as fontes citadas, os links do site nas respostas, a análise do site, os rascunhos, as unidades e o saldo do plano. Cada acesso usa um token próprio. A API está incluída no plano Parceiros. Nos planos Base, Essencial e Negócio não está incluída. Para correr os exemplos desta página, troque o token de exemplo pelo seu.

Criar um token

  1. No painel, em Conta, MCP e API, crie um token com um rótulo que reconheça («Looker», «Zapier»). O valor notado_… aparece uma vez: copie-o ali.
  2. Envie-o em todos os pedidos: Authorization: Bearer notado_….

O limite é de 60 pedidos por minuto, por token. Ao ultrapassar, a API responde 429 com um Retry-After em segundos. O token não volta a ser mostrado: se o perder, revogue-o no mesmo ecrã e crie outro.

Dez endpoints

Todos em https://notado.pt/api/v1, todos GET e só de leitura, confinados à organização do token.

GET /me: organização, plano e saldo

curl -s https://notado.pt/api/v1/me \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Devolve a organização e o plano. No plano Parceiros, também o saldo de créditos do ciclo: dotação, usados, restantes. Num plano sem limite de créditos, allowance vem null. Nos outros planos credits vem null e work_done traz o que o ciclo mediu e corrigiu.

GET /visibility: a série semanal

curl -s "https://notado.pt/api/v1/visibility?weeks=12" \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Uma linha por semana, com visibility e days_measured. A semana sem medições vem "visibility": null com "days_measured": 0. Essa semana está «por medir»: o null distingue-a de uma semana medida com visibilidade 0. O argumento weeks vai de 1 a 52; por omissão, 12.

GET /prompts: perguntas e últimos estados

curl -s https://notado.pt/api/v1/prompts \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Cada pergunta monitorizada com a última medição por motor. Estados possíveis: present, absent, unattributable (não nomeado, fontes só pelo nome) e failed. unattributable é um caso de absent: a resposta foi lida e não nomeia a marca, por isso conta como não nomeada em todas as contas, e as fontes vieram só com nome, por isso fica por saber se o site foi citado. Em failed, appeared vem null: a medição falhou e não diz se a marca apareceu. Motores por medir ficam fora da lista.

GET /citations: citado vs. lido

curl -s "https://notado.pt/api/v1/citations?days=30" \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Hosts citados com citations e citing_runs, hosts que o motor leu sem citar, com read_only_runs, e o read_signal, que só conta as medições em que o motor revelou o que leu (hoje ChatGPT, Perplexity e Claude). Com "runs": 0, os zeros são «por medir». O citation_signal separa as respostas em que o citado se pôde medir (runs) das que não trouxeram fontes com endereço (not_measured_runs), onde o citado fica por medir. O argumento days vai de 1 a 90; por omissão, 30.

GET /answer-links: links do site nas respostas

curl -s "https://notado.pt/api/v1/answer-links?state=partido" \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Os endereços do seu site que os motores citaram, leram ou escreveram nas respostas, com o estado da última verificação, o motivo, a pergunta e o motor de cada aparição. Em counts, partido e inacessivel contam em separado: partido quer dizer que a página não existe; inacessivel quer dizer que o site recusou o pedido ou não respondeu, e não diz nada sobre a página. por_verificar e nao_verificado_robots são links ainda por verificar. Os links escondidos contam à parte, em dismissed, e só entram na lista com include_dismissed=1. Os filtros project_id e state são opcionais; um project_id de outra organização devolve 404. Com "ready": false, a lista vem vazia e counts vem null: por medir.

GET /site-analysis: a análise do site

curl -s https://notado.pt/api/v1/site-analysis \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Para cada site da organização, a última análise legível: score, previous_score, as categorias, as verificações com falha e o histórico. Um site sem análise legível vem com "state": "not_probed" e "score": null: está por medir, e uma nota 0 seria outra conclusão. Em cada categoria, state distingue o que foi medido do que ficou por medir ou não se aplica, com a razão em reason; só as categorias com scored verdadeiro contam para a nota.

GET /drafts: rascunhos para rever

curl -s https://notado.pt/api/v1/drafts \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Os rascunhos de cada site, só de leitura. approved é verdadeiro apenas quando o texto atual é o que foi aprovado, e blocked marca os rascunhos com frases sem facto confirmado, que não se aprovam; blocked_reasons diz porquê. Aprovar não publica nada. Com "ready": false, os rascunhos ainda não estão disponíveis nesta conta e a lista vem vazia.

GET /locations: as unidades

curl -s https://notado.pt/api/v1/locations \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Cada unidade da organização, com name, city, address, is_primary, o site a que pertence (project_id, project_name) e o service_mode. Uma rede com várias unidades num só site e uma rede com um site por unidade leem-se da mesma forma. Em google_business_profile, a ficha Google vem found, not_found, not_applicable num negócio só online, ou not_probed quando não foi lida; só a unidade principal de cada site tem leitura da ficha, e as outras vêm not_probed.

GET /locations/visibility: a série semanal por unidade

curl -s "https://notado.pt/api/v1/locations/visibility?weeks=12" \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Uma linha por unidade, com a série semanal em series e a mesma série por motor em by_engine. Como em /visibility, uma semana sem medições vem "visibility": null com "days_measured": 0: essa semana está por medir. Um motor que nunca mediu essa unidade fica fora de by_engine. O argumento weeks vai de 1 a 52; por omissão, 12. Para ler só algumas unidades, repita location_id (?location_id=3&location_id=5); um número que não é de uma unidade sua fica de fora sem erro. A resposta traz também a janela em window e, em method_marks, os dias em que o método de medição mudou dentro dela.

GET /locations/{id}/corrections: as correções de uma unidade

curl -s https://notado.pt/api/v1/locations/3/corrections \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

As correções ativas que cobrem a unidade: as dela, com "scope": "location", e as do site todo, com "scope": "project", cada uma com kind, applied_at e verification_status. Enquanto a organização não tiver nenhuma correção por unidade, meta.ready vem false e a lista vem vazia: a leitura por unidade ainda não começou nessa conta. Uma unidade de outra organização devolve 404.

Os três endpoints das unidades devolvem a lista em data, por páginas: page e per_page (por omissão 100, no máximo 200), com o total em meta.

A língua da medição

/visibility, /prompts, /citations e /locations/visibility aceitam language, com pt-PT (ou pt) ou en; outro valor dá 422. Cada pedido lê uma língua, e as duas nunca se somam nem se juntam numa média. Sem o parâmetro, cada site lê a língua com mais perguntas ativas, o português em caso de empate. Num site que mede as duas línguas, os números em inglês só vêm com language=en.

curl -s "https://notado.pt/api/v1/visibility?weeks=12&language=en" \
  -H "Authorization: Bearer notado_O_SEU_TOKEN"

Quando pede uma língua, ou quando um site lê o inglês por omissão, meta traz language e uma linha por site em languages: project_id, language, state (measured ou not_measured), label e not_measured_engines. Um site que não mede a língua pedida vem com "state": "not_measured", "language": null e "label": "Não medido em inglês", e os números dele vêm null, nunca 0: não perguntámos, o que não é ausência. Em inglês, not_measured_engines nomeia o Copilot, que não pergunta em inglês a partir de Portugal. Num pedido sem language a um site que lê o português, a resposta é a mesma de sempre.

Looker Studio

O conector do Notado para o Looker Studio lê a API acima, só em leitura, e mostra a visibilidade por semana e as fontes citadas e lidas. Precisa de um plano que inclua a API. Em desenvolvimento: o conector ainda não está na galeria do Looker Studio. Até estar, escreva-nos e ligamos o conector à sua conta. Em Conta, Integrações, o cartão «Looker Studio» tem o botão «Tenho interesse», que nos avisa.

  1. Crie um token em Conta, MCP e API, como descrito acima.
  2. No Looker Studio, acrescente uma fonte de dados e escolha o conector Notado.
  3. Cole o token quando o conector o pedir e escolha os dados: visibilidade por semana ou fontes citadas e lidas.

Uma semana sem medições chega vazia, nunca a zero: no gráfico fica um intervalo, porque está «por medir». O limite de 60 pedidos por minuto é o do token. Para parar de partilhar os dados, revogue o token no mesmo ecrã.

Erros, todos em JSON

StatusQuando
401Token ausente, malformado ou revogado. A mensagem de erro é a mesma nos três casos.
429Limite do minuto atingido; Retry-After diz quanto esperar.
503A API ainda não está ativa nesta instalação.

Para o mesmo token servir um agente de IA em vez de um script, veja Agentes de IA (MCP).

Ainda com dúvidas? Escreva para [email protected]. Respondemos em 1 dia útil, ou em 2 dias úteis no Notado Base, nos dias úteis, das 10:00 às 18:00, hora de Lisboa.

Continuar a ler