Woorden-API

Je sleutel

Stuur de sleutel mee in de header Authorization als bearer-token, of in de header X-API-Key.

Gratis niveau

Met een gratis sleutel mag je 10 keer per dag iets opvragen. De teller begint opnieuw om 00:00 UTC. Elke aanvraag bij een endpoint met gegevens telt als één. De headers X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset laten zien hoeveel je nog hebt.

Endpoints

Alle paden beginnen met /api/v1. De volledige beschrijving staat in het OpenAPI-bestand.

• GET /api/v1/words Woorden die bij de filters passen
• GET /api/v1/words/{word} Alle lemma’s met deze spelling
• GET /api/v1/themes Thema’s met woorden, met aantallen en namen
• GET /api/v1/themes/{theme}/words Woorden in een thema
• GET /api/v1/levels CEFR-niveaus met woorden, met aantallen
• GET /api/v1/levels/{level}/words Woorden op een niveau
• GET /api/v1/word-of-the-day Het woord van vandaag (UTC)
• GET /api/v1/word-of-the-day/{date} Het woord van een dag, JJJJ-MM-DD
• GET /api/v1/random Willekeurige woorden, nooit uit de cache
• GET /api/v1/export/words.json Alle zichtbare woorden als JSON
• GET /api/v1/export/words.csv Alle zichtbare woorden als CSV
• GET /api/v1/meta Gegevensversie, aantallen, zichtbare controlestatussen, licenties. Open, geen sleutel nodig. (Geen sleutel nodig)

OpenAPI-beschrijving (JSON)

Het veld review_status

Elke waarde heeft een review_status die zegt hoe ver ze is gecontroleerd: owner (door de eigenaar ingevoerd of bevestigd), reviewed, imported (uit een open bron), machine (een machinaal concept dat nog geen mens heeft gecontroleerd) en draft. Het endpoint /meta toont welke statussen de API nu stuurt. Kijk naar dit veld als je alleen gecontroleerde gegevens wilt.

Fouten

Elke fout heeft dezelfde vorm: een object error met status, code en message.

• bad_request: 400: een parameter klopt niet. De melding noemt welke.
• unauthorized: 401: de sleutel ontbreekt, is onbekend of is ingetrokken.
• forbidden: 403: deze sleutel geeft geen toegang tot dit eindpunt.
• not_found: 404: er is niets gevonden.
• rate_limited: 429: de sleutel heeft de aanvragen van vandaag gebruikt. De header Retry-After geeft de seconden tot 00:00 UTC.
• server_error: 500: er ging iets mis aan onze kant. Probeer het later opnieuw.

Voorbeeld

Dezelfde aanvraag in curl, JavaScript en Python. Vervang YOUR_KEY door je eigen sleutel en zet die nooit in openbare code.

curl -H "Authorization: Bearer ih_live_YOUR_KEY" \
  "https://inburgering.help/api/v1/words/fiets?lang=en,fa"

const response = await fetch("https://inburgering.help/api/v1/words/fiets?lang=en,fa", {
  headers: { Authorization: "Bearer ih_live_YOUR_KEY" },
});
if (response.status === 429) {
  // Over the limit: try again after this many seconds.
  console.log("Retry after", response.headers.get("Retry-After"));
} else if (!response.ok) {
  console.log((await response.json()).error.message);
} else {
  console.log(await response.json());
}

import requests

response = requests.get(
    "https://inburgering.help/api/v1/words/fiets?lang=en,fa",
    headers={"Authorization": "Bearer ih_live_YOUR_KEY"},
    timeout=10,
)
if response.status_code == 429:
    # Over the limit: try again after this many seconds.
    print("Retry after", response.headers["Retry-After"])
else:
    response.raise_for_status()
    print(response.json())

Versies en wijzigingen

De API is nu versie 1 (/api/v1). Binnen een versie komen er alleen velden en eindpunten bij, dus negeer velden die je niet kent. Een wijziging die een client kan breken krijgt een nieuwe versie; de oude blijft bereikbaar gedurende een aangekondigde termijn voordat hij wordt uitgezet. De wijzigingen staan hieronder.

• v1
  • Eerste versie: woorden, thema’s, niveaus, woord van de dag, willekeurige woorden, export en meta.
  • Sleutels met dagelijkse limieten per niveau; optioneel een maandlimiet, controlestatussen per niveau en rechten per niveau (lezen, export).
  • Themanamen in het Nederlands en Engels; de Perzische, Arabische en Turkse themanamen zijn concepten (het antwoord van themes noemt ze in labels_draft).

Een API-sleutel aanvragen

Sleutels worden nog niet aan nieuwe aanvragers uitgegeven. Kom later terug.