Costruisci con l'API Wordly.

Avvio rapido

Crea un account gratuito, verifica la tua email utilizzando il codice a sei cifre e copia la chiave API mostrata una volta nella dashboard dello sviluppatore.

1. 1
   Crea un account

   Registrati solo con un indirizzo email e una password.

2. 2
   Verifica la tua email

   Inserisci il codice inviato da [email protected]. La verifica garantisce 50 crediti gratuiti.

3. 3
   Memorizza la tua chiave API

   Copia il generato wly_live_... key e mantenerla in una variabile di ambiente lato server.

4. 4
   Effettua una richiesta di prova

   Chiama l'endpoint dell'account per verificare l'autenticazione e visualizzare il saldo rimanente.

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" }
}

URL di base e controllo delle versioni

Tutti gli endpoint di produzione vengono serviti dal seguente URL di base con versione:

La risposta di rottura o le modifiche al comportamento utilizzeranno una nuova versione del percorso. All'interno possono essere introdotti campi aggiuntivi v1, quindi i client dovrebbero ignorare le proprietà di risposta che non riconoscono.

Autenticazione

Gli endpoint autenticati richiedono una chiave API nell'HTTP Authorization intestazione utilizzando lo schema Bearer.

Authorization: Bearer wly_live_your_api_key

Messaggi API localizzati

Imposta la lingua di risposta con ?lang=tr o la norma Accept-Language intestazione. I parametri di query hanno la precedenza. Ogni risposta JSON dichiara la locale selezionata in Content-Language e meta.lang. I codici di errore rimangono stabili in inglese per la gestione programmatica; solo il messaggio leggibile dall'uomo è localizzato.

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

Codici lingua supportati: 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.

Crediti e fatturazione

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 e non elabora l'operazione.

{
  "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"
  }
}

Ciclo di vita della chiave API

Crea chiavi separate per sviluppo, gestione temporanea e produzione. Wordly memorizza solo un hash crittografico di ciascuna chiave; il valore completo viene visualizzato una volta al momento della creazione.

• Assegnare un nome alle chiavi in base all'ambiente o al servizio.
• Utilizzare variabili di ambiente o un archivio segreto gestito.
• Revocare immediatamente una chiave se potrebbe essere stata esposta.
• Ruota le chiavi senza riutilizzare i vecchi valori.
• Non inviare chiavi nelle stringhe di query.

Formato della risposta

Le risposte riuscite utilizzano un livello superiore data oggetto e può includere a meta oggetto. Gli errori utilizzano sempre un livello superiore error oggetto con un carattere leggibile dalla macchina stabile code e leggibile dall'uomo message.

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

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

Conserva il request_id quando si contatta l'assistenza per una richiesta fatturata con successo. JSON è codificato UTF-8 e i client devono inviare Accept: application/json.

Endpoint di produzione

Endpoint del vocabolario

GET /v1/words/{word}

Restituisce una corrispondenza esatta della parola. Utilizzare languages=tr,de,fr per restituire solo le traduzioni richieste. Cataloghi o documenti tradotti costano 1 credito; i profili completamente arricchiti costano 5 crediti.

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

GET /v1/words/search

Cerca con q e facoltativo level, part_of_speech, category, limit, e cursor. I limiti vanno da 1 a 50. Passato meta.next_cursor nella richiesta successiva.

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

GET /v1/words/random

Restituisce da 1 a 20 parole casuali. Filtra per level, part_of_speech, o category. Ogni slot restituito costa un credito.

POST /v1/words/batch

Cerca da 1 a 50 parole univoche in un'unica richiesta. La risposta preserva l'ordine della richiesta e contrassegna ogni elemento con 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

Restituisce tutte le 30 interfacce supportate e le impostazioni locali dei messaggi API. Le traduzioni del vocabolario vengono restituite solo quando disponibili. Questo endpoint è pubblico e costa zero crediti.

Limite di tariffa

Ciascuna chiave API è limitata a 120 richieste accettate per minuto continuativo. Le risposte includono X-RateLimit-Limit e X-RateLimit-Remaining. A 429 rate_limit_exceeded la risposta include 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

Errori

Politica di ripetizione consigliata

Non riprovare 401, 402, o 404 automaticamente. Per transitorio 5xx risposte, utilizzare il backoff esponenziale con jitter e un limite rigoroso ai tentativi. Non creare mai un ciclo illimitato di tentativi poiché ogni richiesta autenticata accettata potrebbe consumare crediti.

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);

Pitone

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);

Dardo / Svolazzo

Non spedire la chiave Wordly all'interno di un'applicazione Flutter. L'esempio appartiene a un backend o a una funzione server Dart attendibile.

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']);
}

Lista di controllo della produzione

• Richieste proxy Wordly tramite un backend affidabile.
• Imposta i timeout di connessione e risposta.
• Maniglia 401, 402, 404, e 5xx separatamente.
• Query GET /v1/account when your application needs the current balance.
• Registra endpoint, stato, latenza e request_id senza registrare la chiave API.
• Utilizza chiavi separate per ambiente e ruotale periodicamente.
• Cache stable vocabulary responses in your backend when appropriate.