German Words API

A REST API that serves random German words with difficulty filtering based on frequency data from external sources.

---

Features

• Random German word generation
• English translations for German words
• Difficulty filtering (beginner, intermediate, advanced)
• Word search functionality (German ↔ English)
• Word statistics and metadata
• External data source integration
• Rate limiting and security headers
• Data refresh capabilities
• Translation management with caching and batch processing

---

🌐 Translation Feature

The API includes English translations for German words, making it perfect for language learning applications!

Translation API Endpoints

POST /api/words/translate

Translate all untranslated words in the database.

curl -X POST http://localhost:3000/api/words/translate

GET /api/words/translate/stats

Get current translation statistics.

curl http://localhost:3000/api/words/translate/stats

POST /api/words/translate/single

Translate a single German word on demand.

curl -X POST -H "Content-Type: application/json" \
     -d '{"word":"haus"}' \
     http://localhost:3000/api/words/translate/single

CLI Translation Tool

Run bulk translation from command line:

npm run translate-words

Bilingual Search Examples

# Search by German word
curl "http://localhost:3000/api/words/search?q=ecke"

# Search by English translation  
curl "http://localhost:3000/api/words/search?q=corner"
# Both return: {"german": "ecke", "english": "corner"}

---

Quick Start

Option 1: Docker (Recommended)

Prerequisites

• Docker and Docker Compose installed

Steps

1. Fetch German word data (required for first run)

npm install
npm run fetch-data

2. Build and run with Docker Compose

docker compose up -d

3. Visit the API

• API Documentation: http://localhost:3000/
• Health Check: http://localhost:3000/health
• Random Word: http://localhost:3000/api/words/random

Docker Commands

# Start the container
docker compose up -d

# Stop the container
docker compose down

# View logs
docker compose logs -f

# Rebuild the image
docker compose up -d --build

---

Option 2: Local Development

1. Install dependencies

npm install

2. Fetch German word data (required for first run)

npm run fetch-data

This will take a few minutes as it fetches data from external APIs.

3. Start the server

npm start

Or for development (with auto-reload):

npm run dev

4. Visit the API

• API Documentation: http://localhost:3000/
• Health Check: http://localhost:3000/health
• Random Word: http://localhost:3000/api/words/random

---

API Endpoints

GET /api/words/random

Get random German words with optional filtering.

Parameters:

• count (1–50) → number of words to return (default: 1)
• difficulty → beginner, intermediate, or advanced
• type → noun, verb, adjective, etc.

Example:

GET /api/words/random?count=5&difficulty=beginner

---

GET /api/words/search

Search German words by German or English text.

Parameters:

• q (required) → search query (minimum 2 characters)
• limit → maximum results (default: 10)

Example:

GET /api/words/search?q=haus&limit=5

---

GET /api/words/difficulties

Get available difficulty levels.

---

GET /api/words/types

Get available word types.

---

GET /api/words/stats

Get word database statistics.

---

POST /api/words/refresh

Refresh word data from external sources.

---

POST /api/words/translate

Translate all German words that don't have English translations.

---

GET /api/words/translate/stats

Get translation statistics and progress.

---

POST /api/words/translate/single

Translate a single German word on demand.

Parameters:

• word (required) → German word to translate

Example:

POST /api/words/translate/single
Content-Type: application/json

{"word": "haus"}

---

Data Sources

• German Dictionary (lorenbrichter/Words) → Primary German word source
• German Wordlist (gambolputty/german-wordlist) → Alternative German word source
• Wiktionary → Translations and definitions enrichment
• MyMemory Translation API → English translations for German words

Translation System

• Smart Caching: Prevents duplicate translation requests
• Rate Limiting: Respects API limits with 1-second delays
• Static Fallbacks: 50+ common German words with built-in translations
• Batch Processing: Handles large datasets efficiently (5 words per batch)
• Persistent Storage: Translations saved permanently to database

Word Filtering

The API intelligently filters words to ensure only authentic German beginner-level words are served:

• German characteristics detection: Umlauts (ä, ö, ü, ß), German patterns (sch, ch, tz, etc.)
• Beginner-friendly: 3-8 character words with high estimated frequency
• Word type classification: Articles, verbs, nouns, pronouns, prepositions, conjunctions
• Length and complexity filtering: Optimized for language learning

Note: Currently serving only beginner difficulty words. Intermediate and advanced levels are planned for future releases.

---

Project Structure

German-api/
├── package.json           # Dependencies and scripts
├── server.js              # Main Express server
├── services/
│   ├── dataFetcher.js     # External API integration
│   └── translationService.js # Translation API integration
├── scripts/
│   ├── fetchData.js       # Data fetching script
│   └── translateWords.js  # Translation CLI tool
├── utils/
│   └── wordProcessor.js   # Word processing logic
├── routes/
│   └── words.js           # API endpoints
├── data/
│   ├── german-words.json  # Generated word database
│   └── translation-cache.json # Translation cache
└── README.md

---

Setup Instructions

1. Run npm install to install dependencies
2. Run npm run fetch-data to populate the word database
3. Run npm run translate-words to add English translations (recommended)
4. Run npm start to start the API server

The API will be available at: http://localhost:3000

Available Scripts

• npm run fetch-data - Fetch German words from external sources
• npm run translate-words - Translate German words to English
• npm start - Start production server
• npm run dev - Start development server with auto-reload

---

License

MIT