Word API

Your key

Send the key in the Authorization header as a bearer token, or in the X-API-Key header.

Free tier

A free key may make 10 calls a day. The count starts again at 00:00 UTC. Every call to a data endpoint counts as one, and the response headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset show where you stand.

Endpoints

All paths start with /api/v1. The full description is the OpenAPI file.

• GET /api/v1/words Words that match the filters
• GET /api/v1/words/{word} Every entry with this spelling
• GET /api/v1/themes Themes that have words, with counts and labels
• GET /api/v1/themes/{theme}/words Words in a theme
• GET /api/v1/levels CEFR levels that have words, with counts
• GET /api/v1/levels/{level}/words Words at a level
• GET /api/v1/word-of-the-day The word of today (UTC)
• GET /api/v1/word-of-the-day/{date} The word of a day, YYYY-MM-DD
• GET /api/v1/random Random words, never cached
• GET /api/v1/export/words.json Every visible word as JSON
• GET /api/v1/export/words.csv Every visible word as CSV
• GET /api/v1/meta Data version, counts, visible review states, licences. Open, no key. (No key needed)

OpenAPI description (JSON)

The review_status field

Every value carries a review_status that says how far it has been checked: owner (entered or confirmed by the owner), reviewed, imported (taken from an open source), machine (a machine draft, not yet reviewed by a person) and draft. The /meta endpoint lists the statuses the API sends right now. Check the field if you need reviewed data only.

Errors

Every error has the same shape: an error object with status, code and message.

• bad_request: 400: a parameter is wrong. The message names it.
• unauthorized: 401: the key is missing, unknown or revoked.
• forbidden: 403: this key does not cover this endpoint.
• not_found: 404: nothing matches.
• rate_limited: 429: the key has used its calls for today. The Retry-After header gives the seconds until 00:00 UTC.
• server_error: 500: something went wrong on our side. Try again later.

Example

The same call in curl, JavaScript and Python. Replace YOUR_KEY with your own key and never put it in public 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())

Versions and changes

The API is at version 1 (/api/v1). Inside a version we only add fields and endpoints, so ignore fields you do not know. A change that could break a client gets a new version; the old one stays reachable for an announced notice period before it is switched off. The changes are listed below.

• v1
  • First version: words, themes, levels, word of the day, random words, export and meta.
  • Keys with daily limits per tier; an optional monthly limit, per-tier review states and per-tier scopes (read, export).
  • Theme labels in Dutch and English; Persian, Arabic and Turkish theme labels are drafts (themes answer lists them in labels_draft).

Request an API key

Keys are not being issued to new requesters yet. Please check back later.