Bouw met Wordly API.

Snelstart

Maak een gratis account aan, verifieer uw e-mailadres met de zescijferige code en kopieer de API-sleutel die eenmaal in uw ontwikkelaarsdashboard wordt weergegeven.

1. 1
   Maak een account aan

   Registreer met alleen een e-mailadres en wachtwoord.

2. 2
   Controleer uw e-mailadres

   Voer de code in die is verzonden door [email protected]. Verificatie levert 50 gratis credits op.

3. 3
   Bewaar uw API-sleutel

   Kopieer het gegenereerde wly_live_... sleutel en bewaar deze in een omgevingsvariabele aan de serverzijde.

4. 4
   Doe een testaanvraag

   Roep het accounteindpunt aan om de authenticatie te verifiëren en het resterende saldo te bekijken.

curl "https://api.wordlyenglish.com/v1/account" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "message": "Authenticated",
    "credits_remaining": 50
  },
  "meta": { "lang": "en" }
}

Basis-URL en versiebeheer

Alle productie-eindpunten worden bediend vanaf de volgende basis-URL met versiebeheer:

Bij het breken van reacties of gedragsveranderingen wordt een nieuwe padversie gebruikt. Binnenin kunnen additieve velden worden geïntroduceerd v1, dus clients moeten responseigenschappen negeren die ze niet herkennen.

Authenticatie

Voor geverifieerde eindpunten is een API-sleutel in de HTTP vereist Authorization header met behulp van het Bearer-schema.

Authorization: Bearer wly_live_your_api_key

Gelokaliseerde API-berichten

Stel de antwoordtaal in met ?lang=tr of de standaard Accept-Language koptekst. Queryparameters hebben voorrang. Bij elk JSON-antwoord wordt de geselecteerde landinstelling gedeclareerd Content-Language en meta.lang. Foutcodes blijven stabiel in het Engels voor programmatische afhandeling; alleen het voor mensen leesbare bericht is gelokaliseerd.

curl "https://api.wordlyenglish.com/v1/account?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept-Language: tr-TR"

Ondersteunde taalcodes: en, tr, de, fr, es, it, pt, nl, pl, ru, uk, ar, fa, he, hi, bn, ur, zh, ja, ko, id, ms, vi, th, sv, no, da, fi, cs, ro.

Kredieten en facturering

Each successful metered request consumes the documented number of credits. Email-verified accounts receive 50 free credits once. Credits are deducted atomically, so concurrent requests cannot spend the same balance twice. Balance lookup through GET /v1/account is free.

Use GET /v1/account when you need the current balance. Other endpoint responses include the operation charge but omit the remaining balance. When the balance is insufficient, the API returns HTTP 402 en verwerkt de bewerking niet.

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your credit balance is exhausted. Add a package or enable pay-as-you-go to continue.",
    "upgrade_url": "/app.php?page=billing"
  }
}

Levenscyclus van API-sleutel

Maak afzonderlijke sleutels voor ontwikkeling, staging en productie. Wordly slaat slechts een cryptografische hash van elke sleutel op; de volledige waarde wordt bij het aanmaken één keer weergegeven.

• Geef sleutels een naam op omgeving of service.
• Gebruik omgevingsvariabelen of een beheerd geheim archief.
• Trek een sleutel onmiddellijk in als deze mogelijk is blootgelegd.
• Roteer sleutels zonder oude waarden te hergebruiken.
• Stuur geen sleutels in queryreeksen.

Antwoordformaat

Succesvolle reacties maken gebruik van een topniveau data object en kan een meta voorwerp. Fouten gebruiken altijd een topniveau error object met een stabiele machinaal leesbaar code en voor mensen leesbaar message.

{
  "data": { ... },
  "meta": {
    "credits_used": 1,
    "request_id": "..."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "..."
  }
}

Houd de request_id wanneer u contact opneemt met de ondersteuning over een succesvol gefactureerd verzoek. JSON is UTF-8-gecodeerd en clients moeten verzenden Accept: application/json.

Productie-eindpunten

Eindpunten van de woordenschat

GET /v1/words/{word}

Retourneert een exacte woordovereenkomst. Gebruik languages=tr,de,fr om alleen gevraagde vertalingen terug te sturen. Catalogus of vertaalde records kosten 1 credit; volledig verrijkte profielen kosten 5 credits.

curl "https://api.wordlyenglish.com/v1/words/water?languages=tr,de" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/search

Zoek met q en optioneel level, part_of_speech, category, limit, en cursor. Limieten variëren van 1 tot 50. Pass meta.next_cursor naar het volgende verzoek.

curl "https://api.wordlyenglish.com/v1/words/search?q=app&level=advanced&limit=20" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/random

Retourneert 1–20 willekeurige woorden. Filter op level, part_of_speech, of category. Elk geretourneerd slot kost één credit.

POST /v1/words/batch

Zoekt tussen de 1 en 50 unieke woorden op in één verzoek. Het antwoord behoudt de verzoekvolgorde en markeert elk item met found.

curl -X POST "https://api.wordlyenglish.com/v1/words/batch?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"words":["water","opportunity"],"languages":["tr","de"]}'

GET /v1/languages

Retourneert alle 30 ondersteunde landinstellingen voor interfaces en API-berichten. Woordenschatvertalingen worden alleen geretourneerd als deze beschikbaar zijn. Dit eindpunt is openbaar en kost nul credits.

Tarieflimiet

Elke API-sleutel is beperkt tot 120 geaccepteerde verzoeken per voortschrijdende minuut. Reacties omvatten X-RateLimit-Limit en X-RateLimit-Remaining. EEN 429 rate_limit_exceeded reactie omvat Retry-After: 60.

Response field reference

Every stable response variable is described below. Additive fields may appear later, so clients should ignore fields they do not recognize.

Vocabulary object

Meta object

Error object

Fouten

Aanbevolen beleid voor opnieuw proberen

Probeer het niet opnieuw 401, 402, of 404 automatisch. Voor voorbijgaand 5xx reacties, gebruik exponentiële uitstel met jitter en een strikte limiet voor nieuwe pogingen. Maak nooit een onbegrensde herhalingslus, omdat elk geaccepteerd, geauthenticeerd verzoek credits kan verbruiken.

JavaScript / Node.js

const response = await fetch('https://api.wordlyenglish.com/v1/account', {
  headers: {
    Authorization: `Bearer ${process.env.WORDLY_API_KEY}`,
    Accept: 'application/json'
  }
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.credits_remaining);

Python

import os
import requests

response = requests.get(
    'https://api.wordlyenglish.com/v1/account',
    headers={
        'Authorization': f'Bearer {os.environ["WORDLY_API_KEY"]}',
        'Accept': 'application/json',
    },
    timeout=15,
)
response.raise_for_status()
print(response.json()['data']['credits_remaining'])

PHP

$curl = curl_init('https://api.wordlyenglish.com/v1/account');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WORDLY_API_KEY'),
    'Accept: application/json',
  ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status >= 400) {
  throw new RuntimeException('Wordly API request failed');
}
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

Darten/fladderen

Verzend de Wordly-sleutel niet in een Flutter-applicatie. Het voorbeeld hoort thuis in een vertrouwde Dart-backend of serverfunctie.

final response = await http.get(
  Uri.parse('https://api.wordlyenglish.com/v1/account'),
  headers: {
    'Authorization': 'Bearer ${Platform.environment['WORDLY_API_KEY']}',
    'Accept': 'application/json',
  },
);

final body = jsonDecode(response.body) as Map<String, dynamic>;
if (response.statusCode >= 400) {
  throw Exception((body['error'] as Map)['code']);
}

Controlelijst voor productie

• Proxy Wordly-aanvragen via een vertrouwde backend.
• Stel verbindings- en reactietime-outs in.
• Handvat 401, 402, 404, en 5xx afzonderlijk.
• Query GET /v1/account when your application needs the current balance.
• Eindpunt, status, latentie en logboekregistratie request_id zonder de API-sleutel te loggen.
• Gebruik afzonderlijke sleutels per omgeving en wissel deze periodiek.
• Cache stable vocabulary responses in your backend when appropriate.