Provedores

Como conectar uma base de indicadores à Acácia e o que acontece na sincronização.

Um provedor é qualquer infraestrutura que sirva indicadores por API e aceite ser catalogada pela Acácia. O primeiro provedor conectado é o Adapta Brasil (MCTI) — e o modelo de integração dele é o contrato que novos provedores seguem. A API interna de scrape (slug geo-indica, kind geo-indica-rest) não é o nome público da fonte.

O princípio: federação, não cópia

A Acácia indexa metadados, não valores:

Na sincronização, a Acácia lê o catálogo do provedor (categorias e definições de indicadores), gera embeddings dos metadados e os guarda no índice vetorial.
Na busca, os valores são consultados ao vivo na API do provedor, a cada requisição.

Isso significa que o dado nunca sai da infraestrutura de quem o publica: o provedor mantém controle, versionamento e a própria medição de uso.

O contrato de API

Para ser sincronizável, um provedor expõe endpoints REST paginados:

Endpoint	Retorna
`GET /indicator-types`	As categorias do catálogo (slug, nome, contagem).
`GET /indicator-types/:slug/indicators`	As definições de indicadores de uma categoria.
`GET /indicators/by-geocode/:geocode`	Valores de um território, filtráveis por `type`, `indicator` e `year`.
`GET /indicator-values?indicatorId=`	A série de valores de um indicador, do ano mais recente para trás.
`GET /ibge/cities?name=`	Resolução de nome de município para geocode IBGE (busca fuzzy).

Todas as respostas paginadas seguem o envelope { "data": [...], "pagination": { "page", "totalPages" } }.

O registro do provedor

Ao conectar, o provedor declara os metadados DCAT que alimentarão o bloco attribution de toda resposta:

{
  "slug": "geo-indica",
  "name": "Adapta Brasil",
  "kind": "geo-indica-rest",
  "baseUrl": "https://indicadores-api-production.up.railway.app",
  "publisherName": "Adapta Brasil / MCTI",
  "publisherUrl": "https://adaptabrasil.mcti.gov.br",
  "license": "CC-BY 4.0"
}

publisherName, publisherUrl e license são obrigatórios — sem eles não há como montar a citação, e sem citação o dado não circula na Acácia.

O que acontece na sincronização

A Acácia percorre GET /indicator-types e, para cada categoria, pagina as definições de indicadores.
Para cada definição, monta um texto de busca (nome + categoria + publicador) e gera o embedding (1536 dimensões).
As definições entram no índice vetorial do catálogo — novas são inseridas, existentes são atualizadas.
O provedor recebe um carimbo de sincronização (lastSyncAt, status, contagem de indicadores).

A partir daí, os indicadores do provedor aparecem nas buscas semânticas, e cada resultado consulta a API dele em tempo real.

Outros caminhos de entrada

O provedor com API própria é o caminho preferencial, mas não o único previsto no roadmap:

Publicação direta — organizações que não mantêm API poderão publicar datasets no formato canônico diretamente na Acácia.
Sugestão de fontes — a comunidade poderá indicar portais de terceiros para triagem; fontes aprovadas passam por ingestão assistida (scraping estruturado + revisão humana no painel interno).

Quer conectar uma base? O catálogo do Adapta Brasil entrou com 199 indicadores em uma tarde — o contrato acima é tudo o que foi preciso.