Benchmark — Dokumentation

Benchmark-funktioner används via portalen och organisationens inloggade Firebase-session. Det här är interna Pro-endpoints, inte Skolkolls publika API-roadmap eller en API-nyckelprodukt.

Endpoints:

// Grupp-CRUD:
POST   /api/pro/benchmark/               Skapa grupp
GET    /api/pro/benchmark/               Lista alla grupper
GET    /api/pro/benchmark/{id}           Hämta grupp med medlemmar
PUT    /api/pro/benchmark/{id}           Uppdatera (namn, beskrivning, medlemmar)
DELETE /api/pro/benchmark/{id}           Ta bort grupp

// Beräkning och export:
POST   /api/pro/benchmark/{id}/compute  Beräkna statistik
POST   /api/pro/benchmark/{id}/export   Exportera (csv/xlsx/pdf)

// Matchning (kräver autentisering):
POST   /api/pro/benchmark/match                Socioekonomisk matchning

// Referensdata (öppna, ingen autentisering):
GET    /api/pro/benchmark/scb-groups           SCB kommungrupper
GET    /api/pro/benchmark/scb-groups/{code}/members  Kommuner i en grupp

Exempel: Skapa grupp och beräkna jämförelse

// 1. Hämta kommuner i SCB-gruppen "Större stad":
GET /api/pro/benchmark/scb-groups/B3/members
→ { "members": [{ "kommunKod": "0380", "namn": "Uppsala" }, ...] }

// 2. Skapa en grupp med dessa kommuner:
POST /api/pro/benchmark/
{
  "name": "SCB B3 — Större städer",
  "entityType": "municipality",
  "description": "Alla kommuner i SCB-gruppen Större stad (2017)",
  "members": [{"id": "0380"}, {"id": "0580"}, {"id": "0680"}]
}

// 3. Beräkna med filter:
POST /api/pro/benchmark/{groupId}/compute
{
  "metrics": ["meritvardeSnitt", "kostnadPerElev", "behorighetsgrad"],
  "school_type": "Grundskola",
  "provider_type": "enskild",
  "min_pupils": 50,
  "max_pupils": 500
}

// 4. Exportera till Excel:
POST /api/pro/benchmark/{groupId}/export
{ "format": "xlsx", "metrics": ["meritRating9", "eligibleYR9"] }
→ Excel-fil (Content-Disposition: attachment)

// PDF-export (asynkron):
{ "format": "pdf" }
→ 202 { "jobId": "...", "status": "queued" }
// Polla: GET /api/pro/reports/jobs/{jobId}

Detaljer:

Skapa grupp — name (2-80 tecken, obligatoriskt), entityType (school/municipality/provider), members (kan vara tom), description (valfri, max 500 tecken).

Uppdatera grupp — partial update: skicka bara de fält du vill ändra. entityType kan inte ändras efter skapande.

Compute — kräver minst 2 medlemmar i gruppen. Svaret inkluderar: groupId, groupName, entityType, computedAt, members (med metrics + percentileRank per KPI), groupStats (med mean, median, stdDev, p10, p25, p75, p90, min, max, n per KPI), samt notFound/filtered om relevant.

Filter (compute/export): school_type, provider_type ("kommun"/"enskild"), min_pupils/max_pupils, municipality. Filtrerade medlemmar rapporteras i filtered-arrayen.

Matchning: POST /api/pro/benchmark/match med { "kommunKod": "0180", "n": 10 } returnerar de N mest socioekonomiskt liknande kommunerna.

Max: 50 grupper per org, 100 medlemmar per grupp.

Felkoder: 400 (valideringsfel), 403 (saknar benchmark-behörighet; CSV- och XLSX-export kräver dessutom att paketet innehåller export och att du har export-behörighet eller är administratör; PDF kräver bara benchmark), 404 (grupp/organisation hittades inte).