Publieke koppeling

API Documentatie

De KNZB Competitiemodule biedt een publieke, read-only JSON API voor verenigingen, webmasters en leveranciers. De endpoints bevatten uitsluitend openbare competitiegegevens, vereisen geen login en zijn bedoeld voor clubwebsites, dashboards, ClubCast-integraties en narrowcasting.

Alle responses bevatten api_version: "1.0". De API gebruikt server-side caching van 300 seconden. Ververs gegevens daarom bij voorkeur niet vaker dan één keer per vijf minuten.

Endpoint-overzicht

Endpoint	Doel	Voorbeeld
`/api/teamstand.php`	Stand van de context waarin één team uitkomt. Zonder `team` wordt team 1 gebruikt.	`?depotnr=05-014` of `?depotnr=05-014&team=2`
`/api/contextstand.php`	Volledige stand van een klasse/divisie/poule.	`?klasse=1B`
`/api/vereniging.php`	Overzicht van alle competitieteams van één vereniging.	`?depotnr=05-014` of `?club=ZV+De+Waterkip`
`/api/seizoenen.php`	Beschikbare seizoenen.	geen parameters
`/api/klasses.php`	Beschikbare klassecodes.	geen parameters

Interactieve hulpmodule

Live API Tester

Vul hieronder een depotnummer, verenigingsnaam, teamnummer of klasse in en test direct welke JSON de API teruggeeft.

Tip: gebruik deze tester om de juiste URL te bepalen en plak daarna de embed-code op de website van je vereniging.

Depotnummer / clubcode / verenigingsnaam Gebruik bij voorkeur het depotnummer. Een exacte verenigingsnaam met spaties mag ook; de tester zet deze automatisch om naar een geldige URL.

Teamnummer optioneel Leeg laten gebruikt automatisch het enige team van de vereniging; bij meerdere teams wordt team 1 gebruikt.

Klasse / contextcode Bijvoorbeeld E, 1A, 1B, A1, B3 of C5.

Metadata endpoint

Endpoint: https://zwemcompetitie.knzb.nl/competitieservice/api/teamstand.php?depotnr=05-014&team=1

Nog geen API-call uitgevoerd.

{}

Parameters

Endpoint	Parameter	Type	Verplicht	Voorbeeld
teamstand	`depotnr`	depotnummer	ja*	`05-014`
teamstand	`club`	exacte verenigingsnaam	ja*	`ZV+De+Waterkip`
teamstand	`team`	nummer	nee	`1`; leeg = automatisch
contextstand	`klasse`	code	ja	`E`, `1A`, `A1`
vereniging	`depotnr` of `club`	depotnummer of exacte verenigingsnaam	ja	`05-014` of `ZV+De+Waterkip`

* Gebruik óf depotnr óf club. Depotnummer heeft de voorkeur omdat verenigingsnamen spellinggevoelig zijn. Spaties en bijzondere tekens in namen moeten URL-gecodeerd worden; de live tester doet dit automatisch.

Voorbeeldresponse teamstand

{
  "api_version": "1.0",
  "success": true,
  "context": {
    "seizoen": "2025-2026",
    "klasse": "Eerste Divisie B",
    "groep": "1B"
  },
  "requested_team": {
    "naam": "DWK",
    "depotnr": "05-014",
    "team": 1,
    "positie": 1
  },
  "stand": [
    {
      "positie": 1,
      "naam": "DWK",
      "depotnr": "05-014",
      "team": 1,
      "punten": 72888,
      "ronde_1": 22873,
      "ronde_2": 24178,
      "ronde_3": 25837,
      "ronde_4": null,
      "ronde_5": null,
      "pd_status": "promotie",
      "pd_label": "Promoveert naar Eredivisie",
      "is_requested": true
    }
  ]
}

Voorbeeldresponse vereniging

{
  "api_version": "1.0",
  "success": true,
  "vereniging": {
    "naam": "DWK",
    "depotnr": "05-014"
  },
  "seizoen": "2025-2026",
  "teams": [
    {
      "team": 1,
      "klasse": "1B",
      "klasse_label": "Eerste Divisie B",
      "positie": 1,
      "punten": 72888,
      "pd_status": "promotie",
      "pd_label": "Promoveert naar Eredivisie"
    }
  ]
}

Embed Widget

Plaats onderstaande code op een clubwebsite om automatisch de stand van één team te tonen. De widget gebruikt pure JavaScript, laadt geen externe libraries en doet één API-call.

<script
src="https://zwemcompetitie.knzb.nl/competitieservice/embed/stand.js"
data-depotnr="05-014"
data-team="1">
</script>

data-depotnr is het depotnummer van de vereniging. data-team is optioneel; zonder teamnummer wordt automatisch het enige team van de vereniging gebruikt, of team 1 bij meerdere teams. Gebruik bij voorkeur data-depotnr. Als alleen een verenigingsnaam beschikbaar is, kan data-club="ZV De Waterkip" worden gebruikt.

Teamwidget zonder teamnummer

<script
src="https://zwemcompetitie.knzb.nl/competitieservice/embed/stand.js"
data-depotnr="05-014">
</script>

Teamwidget met verenigingsnaam

<script
src="https://zwemcompetitie.knzb.nl/competitieservice/embed/stand.js"
data-club="ZV De Waterkip">
</script>

Voorbereid voor verenigingswidget

<script
src="https://zwemcompetitie.knzb.nl/competitieservice/embed/stand.js"
data-depotnr="05-014"
data-view="vereniging">
</script>

Deze verenigingsweergave is alvast gedocumenteerd voor toekomstige uitbreiding van de widget. Het onderliggende endpoint /api/vereniging.php is al beschikbaar.

Technische details

Content-Type: application/json; charset=utf-8.
CORS staat standaard open met Access-Control-Allow-Origin: *. Dit kan later in includes/api_functions.php worden beperkt tot toegestane domeinen.
Cachemap: cache/api/, cacheduur: 300 seconden.
Gebruik alleen GET-requests. De API is read-only.
Foutresponses gebruiken success: false met een foutmelding en passende HTTP-statuscode.