> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semantika.pt/llms.txt
> Use this file to discover all available pages before exploring further.

# Conector Data Studio

> Guia completo para ligar os dados GEO da Semantika ao Data Studio e montar o primeiro relatório.

O conector Semantika importa visibilidade GEO (ChatGPT, Claude, Gemini, Perplexity, Google AI Overviews) para o [Data Studio](https://lookerstudio.google.com/). Serve para relatórios e dashboards à medida. Não substitui o [dashboard da Semantika](/dashboard/visibility-overview). Data Studio (antes Looker Studio) é a ferramenta gratuita da Google.

## Para que serve

<CardGroup cols={3}>
  <Card title="Última análise" icon="chart-line">
    Vês os dados da última análise do workspace, no intervalo de datas do relatório.
  </Card>

  <Card title="Gráficos à medida" icon="filter">
    Montas tabelas e filtros por prompt, domínio e país que o dashboard não tem.
  </Card>

  <Card title="Partilha" icon="share-nodes">
    Envia o relatório à equipa ou ao cliente, a partir do Data Studio.
  </Card>
</CardGroup>

## Antes de começares

<CardGroup cols={3}>
  <Card title="Marca no workspace" icon="building">
    Conta Semantika com pelo menos uma marca no workspace.
  </Card>

  <Card title="Acesso à API" icon="key" href="/integrations/api">
    O plano tem de ter **Acesso à API (beta)**. Sem isto, a secção API Key nem aparece e o conector devolve 403.
  </Card>

  <Card title="Conta Google" icon="globe" href="https://lookerstudio.google.com/">
    Conta Google com acesso ao Data Studio.
  </Card>
</CardGroup>

## Como ligar a fonte

<Card title="Abrir o Data Studio" icon="arrow-up-right-from-square" href="https://lookerstudio.google.com/">
  Autentica-te na Google. O link directo do conector Semantika entra neste cartão quando o deployment versionado for publicado.
</Card>

<Steps>
  <Step title="Abre o conector">
    Abre o conector Semantika no Data Studio. Tens de estar autenticado na Google.
  </Step>

  <Step title="Gera o token na Semantika">
    Na Semantika, vai a **Definições do workspace → API Key**. Não há várias chaves, não há scope por projeto e não dás um nome à chave.

    1. Clica **Gerar API token**.
    2. Copia o valor já: a app não o volta a mostrar.
    3. Confirma que o token começa por `sem_`.

    Há **um** token por workspace. Regenerar ou revogar invalida o anterior: o conector e a [API REST](/integrations/api) param até colares o novo.

    <Warning>
      Não uses o Personal access token da secção MCP (Claude, Cursor). São credenciais diferentes. O conector só aceita o token `sem_…` da secção API Key.
    </Warning>
  </Step>

  <Step title="Cola o token no Data Studio">
    No campo **Token da API** (placeholder `sem_…`), cola o token. Clica **Next** e depois **Connect**.
  </Step>

  <Step title="Adiciona a fonte ao relatório">
    Quando carregar, clica **Create Report** e depois **Add to report**.
  </Step>
</Steps>

<Note>
  O conector só funciona com um API token `sem_…` válido e com acesso à API no plano. Se já tinhas uma fonte Data Studio, volta a ligar e troca a fonte no relatório.
</Note>

## Campos disponíveis

A tabela tem **uma linha por data × marca × motor × prompt × URL de fonte**. Visibilidade, Share of Voice e Sentimento repetem-se nas linhas do mesmo dia e motor: a agregação certa é a média, não a soma. País, prompt e domínio filtram a mesma tabela.

A leitura destas métricas no dashboard está em [Métricas](/concepts/metrics).

<Note>
  Uma marca sem runs concluídos ainda pode ter linhas só com snapshot (visibilidade, Share of Voice, sentimento). `engine`, `prompt` e URLs vêm vazios. Um gráfico por motor ignora essas linhas.
</Note>

### Dimensões

| Name           | Display Name | Description                                                                                                                |
| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| date           | Data         | Dia da análise (`YYYYMMDD` no Data Studio). Granularidade: **Dia**. Usa-a no eixo temporal.                                |
| brand          | Marca        | Nome da marca (projeto) no workspace. Agrupa linhas. Não uses como métrica.                                                |
| engine         | Motor        | ChatGPT, Claude, Gemini, Perplexity, Google AI Overviews e os outros motores ativos. Agrupa linhas. Não uses como métrica. |
| workspace      | Workspace    | Nome do workspace da API key. Uma key nunca vê outro workspace. Não uses como métrica.                                     |
| country\_code  | País         | Código [ISO 3166-1 alfa-2](https://www.iso.org/obp/ui/#search/code/) do mercado (PT, ES, …).                               |
| prompt         | Prompt       | Texto do prompt desta resposta. Agrupa linhas. Não uses como métrica.                                                      |
| source\_url    | URL          | URL da fonte nesta resposta.                                                                                               |
| source\_domain | Domínio      | Domínio da fonte.                                                                                                          |

### Métricas

A agregação abaixo é a que o conector declara. Se a mudares no gráfico, os números deixam de bater certo com o dashboard.

| Name                  | Display Name   | Description                                                                                                                                                         |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visibility            | Visibilidade   | Média (`AVG`). Menções da marca neste motor, 0–100. É a mesma série do dashboard, por run/batch, não por uma janela de calendário inventada.                        |
| sov                   | Share of Voice | Média (`AVG`). Percentagem das menções desse dia que são da marca.                                                                                                  |
| sentiment             | Sentimento     | Média (`AVG`). Sentimento da marca nas respostas desse dia.                                                                                                         |
| citation              | Citação        | Soma (`SUM`). 1 por URL de fonte nesta linha; se a resposta não tem URL, usa o count de citações guardado. A soma no gráfico é o número de vezes que a URL aparece. |
| retrieval             | Retrieval      | Soma (`SUM`). 1 se esta linha tem fonte, 0 se não. A soma é o número de recuperações com URL.                                                                       |
| retrieval\_percentage | Retrieval %    | Média (`AVG`). 100 se a linha tem fonte, 0 se não.                                                                                                                  |
| position              | Posição        | Média (`AVG`). Posição da marca nesta resposta.                                                                                                                     |
| usage                 | Usage          | Soma (`SUM`). 1 por URL de fonte nesta linha. A soma é o usage.                                                                                                     |

## O primeiro relatório

<CardGroup cols={3}>
  <Card title="Cria o relatório" icon="file-plus">
    Depois de ligar a fonte, clica **CREATE REPORT**. O intervalo de datas é obrigatório: sem datas, o conector não devolve linhas.
  </Card>

  <Card title="Visibilidade por motor" icon="chart-line" href="https://lookerstudio.google.com/">
    Eixo **Data**, métrica **Visibilidade**, detalhe **Motor**. Granularidade: **Dia**. Confirma que Visibilidade fica em média, não em soma.
  </Card>

  <Card title="Filtra o recorte" icon="sliders">
    Adiciona controlos de **País**, **Prompt** e **Domínio**. Filtram a mesma tabela; não criam outra fonte.
  </Card>
</CardGroup>

Os restantes tipos de gráfico estão na [documentação do Data Studio](https://support.google.com/lookerstudio/answer/6290789).

## Problemas frequentes

<AccordionGroup>
  <Accordion title="O token foi recusado (401 ou 403)">
    Gera um token novo em **Definições do workspace → API Key** e cola-o outra vez ao ligar a fonte.

    Causas típicas: colaste o Personal access token da secção MCP em vez do `sem_…`; regeneraste o token e a fonte ainda tem o antigo; o plano não tem **Acesso à API (beta)** (403).
  </Accordion>

  <Accordion title="Não há dados neste intervalo">
    Alarga as datas do relatório ou espera pela próxima análise. O conector recusa uma tabela vazia: não desenha o gráfico a zeros. Os pontos seguem análises concluídas, na cadência do teu plano, não um fluxo contínuo minuto a minuto.
  </Accordion>

  <Accordion title="Regeneraste o token e o relatório parou">
    A fonte antiga fica inválida. Volta a ligar a fonte no relatório e troca-a para a nova.
  </Accordion>

  <Accordion title="Os dados não atualizam">
    Espera uns minutos e faz refresh da fonte. A API pode servir a resposta anterior durante cerca de 5 minutos.
  </Accordion>

  <Accordion title="O Data Studio devolve um erro HTTP ou JSON inválido">
    Tenta mais tarde. O problema está no pedido, não na configuração do relatório.
  </Accordion>
</AccordionGroup>

## Ajuda

Se o problema não está na lista, [fala connosco](https://semantika.pt/fala-connosco) ou escreve para [mauro@semantika.pt](mailto:mauro@semantika.pt). Inclui o que falhou e um print.


## Related topics

- [Detalhe da marca](/api-reference/detalhe-da-marca.md)
- [FAQ da Semantika: produto, planos, dados e conta](/help/faq.md)
- [White-label: funcionalidade planeada](/features/white-label.md)
- [Métricas: como ler os resultados recolhidos](/concepts/metrics.md)