🇩🇪 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
• 🎯 Difficulty filtering (beginner, intermediate, advanced)
• 🔍 Word search functionality
• 📊 Word statistics and metadata
• 🌐 External data source integration
• ⚡ Rate limiting and security headers
• 🔄 Data refresh capabilities

---

Quick Start

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.

---

📚 Data Sources

• 📊 German Frequency Words → German frequency data
• 📝 OpenTaal → German wordlist
• 📖 Wiktionary → translations and definitions

---

🗂️ Project Structure

German-api/
├── package.json           # Dependencies and scripts
├── server.js              # Main Express server
├── services/
│   └── dataFetcher.js     # External API integration
├── scripts/
│   └── fetchData.js       # Data fetching script
├── utils/
│   └── wordProcessor.js   # Word processing logic
├── routes/
│   └── words.js           # API endpoints
├── data/
│   └── german-words.json  # Generated word database
└── 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 start to start the API server

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

---

📄 License

MIT