Guia Completo da API de Análise (POST /v1/analytics/query)

O endpoint POST /v1/analytics/query é o coração do motor analítico do SusConecta. Ele permite realizar consultas multi-métricas, agregações espaciais, séries temporais e taxas per capita em menos de 50ms.

---

📋 Especificação do Endpoint

• Método: POST
• Caminho: /v1/analytics/query
• Autenticação: Authorization: Bearer <API_KEY> (Capability exigida: analytics.query.read)
• Content-Type: application/json

---

📐 Estrutura Completa do Payload de Requisição

{
  "metrics": [
    "bed_capacity_existing",
    "bed_capacity_sus",
    "beds_existing_per_100k"
  ],
  "group_by": ["municipality"],
  "filters": [
    {
      "dimension": "state",
      "operator": "IN",
      "value": ["GO", "MT"]
    },
    {
      "dimension": "municipality",
      "operator": "IN",
      "value": [5208707, 5106174]
    }
  ],
  "limit": 100,
  "offset": 0
}

---

🗺️ Modos de Consulta Homologados

1. Agrupamento por Município

Retorna linhas individualizadas para cada município do escopo territorial:

• group_by: ["municipality"]
• Retorna código IBGE, nome do município e sigla da UF.

2. Agrupamento por Estado (Multiestado)

Permite comparar totais estaduais consolidados:

• group_by: ["state"]
• filters: [{"dimension": "state", "operator": "IN", "value": ["GO", "MT"]}]
• Retorna uma linha para Goiás e uma linha para Mato Grosso.

3. Total do Escopo Selecionado (Consolidação Única)

Permite somar todo o escopo de municípios e estados selecionados em um único total consolidado:

• group_by: []
• Retorna 1 linha com o label neutro "Total do escopo selecionado".

4. Taxas Demográficas por 100 Mil Habitantes

Métricas derivadas com sufixo _per_100k (ex: beds_existing_per_100k, equipment_existing_per_100k) utilizam automaticamente o denominador populacional do Censo IBGE correspondente, recalculando a taxa de forma matematicamente precisa no nível de agrupamento solicitado.

---

⚡ Exemplos Práticos de Chamada

cURL

curl -X POST "https://api.susconecta.com.br/v1/analytics/query" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["bed_capacity_existing"],
    "group_by": ["municipality"],
    "filters": [{"dimension": "state", "operator": "EQ", "value": "GO"}]
  }'

TypeScript / Node.js

const response = await fetch(
  "https://api.susconecta.com.br/v1/analytics/query",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      metrics: ["bed_capacity_existing"],
      group_by: ["state"],
      filters: [{ dimension: "state", operator: "IN", value: ["GO", "MT"] }],
    }),
  },
);
const result = await response.json();