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

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.

---

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