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
- 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. - 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.
- Crie um token em Conta, MCP e API, como descrito acima.
- No Looker Studio, acrescente uma fonte de dados e escolha o conector Notado.
- 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
| Status | Quando |
|---|---|
| 401 | Token ausente, malformado ou revogado. A mensagem de erro é a mesma nos três casos. |
| 429 | Limite do minuto atingido; Retry-After diz quanto esperar. |
| 503 | A 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).