🔍 Engoro Lexicon API

Public API for word search, filtering, and discovery. Powered by Cloudflare Workers + D1.

Endpoints

GET /api/v1/words/search

Search words by query string

Query Parameters:

Parameter	Type	Required	Description
q	string	Yes	Search query (min 2 chars)
limit	number	No	Results per page (default: 20, max: 100)
offset	number	No	Pagination offset (default: 0)
locale	string	No	Include translation for locale (e.g. vi-VN)

Example:

curl 'https://api.engoro.com/api/v1/words/search?q=hello&limit=10'

GET /api/v1/words

Filter words by criteria

Query Parameters:

Parameter	Type	Description
difficulty	number	1-5 scale (comma-separated for multiple)
pos	string	Part of speech (noun, verb, etc)
frequency	string	common, uncommon, rare
cefrLevel	string	A1, A2, B1, B2, C1, C2
sortBy	string	difficulty, frequency, alphabetical
limit	number	Results per page (default: 20)
offset	number	Pagination offset (default: 0)

GET /api/v1/words/:id

Get a specific word by ID

Example:

curl 'https://api.engoro.com/api/v1/words/1?locale=vi-VN'

GET /api/v1/suggestions

Get word suggestions for autocomplete

Parameter	Type	Description
q	string	Search query (min 1 char)
limit	number	Max results (default: 10, max: 50)
locale	string	Include translation for locale

GET /api/v1/random

Get random words

Parameter	Type	Description
count	number	Number of words (default: 5, max: 50)
difficulty	number	Optional difficulty filter (1-5)

GET /api/v1/translate

Translate a word to a specific locale

Query Parameters:

Parameter	Type	Required	Description
word	string	Yes	Word to translate
locale	string	Yes	Target locale (e.g., vi-VN, zh-CN)

How it works:

First checks D1 database for existing translation
If found, returns database translation with source: "database"
If not found, attempts LLM translation with source: "llm"
Returns null if translation not available

Example:

curl 'https://api.engoro.com/api/v1/translate?word=hello&locale=vi-VN'

Response:

{
  "success": true,
  "data": {
    "word": "hello",
    "locale": "vi-VN",
    "translation": "xin chào",
    "source": "database"
  }
}

GET /api/v1/stats

Get API statistics (total words, locales, distribution)

Response Format

Success (200):

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 1000,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  },
  "meta": {
    "queryTime": "12.5ms"
  }
}

Error (400/404/500):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query parameter 'q' is required"
  }
}

Features

✅ Fast search at the edge (Cloudflare)
✅ Flexible filtering (difficulty, POS, frequency, CEFR level)
✅ Multi-locale support with translations
✅ Autocomplete optimization
✅ CORS enabled for browser requests
✅ Consistent error handling

Status

API Version: v1

Database: Cloudflare D1 (SQLite)

Rate Limiting: None (subject to change)