217 lines
5.2 KiB
Markdown
217 lines
5.2 KiB
Markdown
# DDB API Key - Step-by-Step Registration Guide
|
|
|
|
## 🎯 Goal
|
|
Get your Deutsche Digitale Bibliothek (DDB) API key to harvest Archivportal-D data.
|
|
|
|
---
|
|
|
|
## 📍 Exact Steps to Get API Key
|
|
|
|
### Step 1: Register for Account (5 minutes)
|
|
|
|
1. **Visit DDB Portal**:
|
|
```
|
|
https://www.deutsche-digitale-bibliothek.de/
|
|
```
|
|
|
|
2. **Click "Anmelden" (Login)** button:
|
|
- Located in top-right corner of page
|
|
- Blue button that says "Anmelden"
|
|
|
|
3. **On login modal, click "Registrieren" (Register)**:
|
|
- Should see registration form
|
|
- Or navigate directly to: https://www.deutsche-digitale-bibliothek.de/user/register
|
|
|
|
4. **Fill registration form**:
|
|
- Email address
|
|
- Username
|
|
- Password (minimum requirements shown on form)
|
|
- Accept terms of service
|
|
|
|
5. **Submit registration**
|
|
|
|
6. **Verify email**:
|
|
- Check inbox for verification email from DDB
|
|
- Click verification link
|
|
- ⏱️ Email usually arrives within 1-2 minutes
|
|
|
|
---
|
|
|
|
### Step 2: Log In (1 minute)
|
|
|
|
1. **Go back to DDB portal**:
|
|
```
|
|
https://www.deutsche-digitale-bibliothek.de/
|
|
```
|
|
|
|
2. **Click "Anmelden" button** (top right)
|
|
|
|
3. **Enter credentials**:
|
|
- Username or email
|
|
- Password
|
|
|
|
4. **Click login button**
|
|
|
|
---
|
|
|
|
### Step 3: Navigate to API Key Page (1 minute)
|
|
|
|
**Option A - Direct URL** (fastest):
|
|
```
|
|
https://www.deutsche-digitale-bibliothek.de/user/apikey
|
|
```
|
|
|
|
**Option B - Via Menu** (if direct URL doesn't work):
|
|
1. After logging in, look for account menu (usually your username in top-right)
|
|
2. Click on your account name
|
|
3. Select "Meine DDB" (My DDB)
|
|
4. Look for "API" or "API-Schlüssel" (API Key) section
|
|
|
|
---
|
|
|
|
### Step 4: Generate API Key (1 minute)
|
|
|
|
On the API key page (`/user/apikey`):
|
|
|
|
1. **Look for button**: "API-Schlüssel erstellen" or "Generate API Key"
|
|
|
|
2. **Click the button**
|
|
|
|
3. **Copy the key**:
|
|
- Key will be a long string like: `ddb_abc123xyz456def789...`
|
|
- ⚠️ **IMPORTANT**: Copy it immediately and save it securely
|
|
- DDB may not show it again after you leave the page
|
|
|
|
4. **Save the key**:
|
|
- Password manager (recommended)
|
|
- Or secure note file
|
|
- ❌ Do NOT commit to git (it's in `.gitignore`)
|
|
|
|
---
|
|
|
|
## 🔧 Add Key to Harvester Script
|
|
|
|
Once you have your API key:
|
|
|
|
```bash
|
|
cd /Users/kempersc/apps/glam
|
|
nano scripts/scrapers/harvest_archivportal_d_api.py
|
|
```
|
|
|
|
**Edit line 21**:
|
|
|
|
```python
|
|
# BEFORE (line 21):
|
|
API_KEY = "YOUR_API_KEY_HERE"
|
|
|
|
# AFTER (line 21):
|
|
API_KEY = "ddb_abc123xyz456def789..." # Your actual key
|
|
```
|
|
|
|
Save and exit (Ctrl+O, Enter, Ctrl+X in nano).
|
|
|
|
---
|
|
|
|
## ✅ Verify API Key Works (Optional Test)
|
|
|
|
Test that your key is valid:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer YOUR_KEY_HERE" \
|
|
"https://api.deutsche-digitale-bibliothek.de/search?query=*&rows=1"
|
|
```
|
|
|
|
**Expected response**: JSON with search results
|
|
**Error 401**: Key is invalid or expired
|
|
**Error 403**: Key doesn't have permissions
|
|
|
|
---
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### Issue: Can't Find "Registrieren" Button
|
|
|
|
**Solution**: Look for these German words on the login page:
|
|
- "Neu registrieren" (Register new)
|
|
- "Konto erstellen" (Create account)
|
|
- "Registrierung" (Registration)
|
|
|
|
### Issue: Verification Email Doesn't Arrive
|
|
|
|
**Solutions**:
|
|
- Check spam/junk folder
|
|
- Wait 5-10 minutes (email servers can be slow)
|
|
- Request new verification email (usually button on login page)
|
|
- Contact DDB support: https://www.deutsche-digitale-bibliothek.de/contact
|
|
|
|
### Issue: API Key Page is Empty
|
|
|
|
**Solutions**:
|
|
- Make sure you're logged in (check top-right for your username)
|
|
- Try direct URL: https://www.deutsche-digitale-bibliothek.de/user/apikey
|
|
- Clear browser cache and cookies
|
|
- Try different browser
|
|
|
|
### Issue: Can't Generate API Key
|
|
|
|
**Possible reasons**:
|
|
- Account not verified yet (check email)
|
|
- Need to accept additional API terms of service (look for checkbox)
|
|
- API limit reached (unlikely for new accounts)
|
|
|
|
**Solution**: Contact DDB support with screenshot
|
|
|
|
---
|
|
|
|
## 📚 Additional Resources
|
|
|
|
- **DDB API Documentation**: https://api.deutsche-digitale-bibliothek.de/
|
|
- **DDB Contact Form**: https://www.deutsche-digitale-bibliothek.de/contact
|
|
- **DDB User Guide** (German): https://www.deutsche-digitale-bibliothek.de/content/nutzungshinweise
|
|
|
|
---
|
|
|
|
## 🔒 Security Notes
|
|
|
|
- ✅ **DO**: Store key in password manager or secure note
|
|
- ✅ **DO**: Keep key private (it's tied to your account)
|
|
- ✅ **DO**: Add to `.gitignore` before committing code
|
|
- ❌ **DON'T**: Share key publicly
|
|
- ❌ **DON'T**: Commit key to git repository
|
|
- ❌ **DON'T**: Post key in forums/chat (even for help)
|
|
|
|
---
|
|
|
|
## ⏱️ Total Time: ~10 Minutes
|
|
|
|
- Step 1 (Register): 5 minutes
|
|
- Step 2 (Log in): 1 minute
|
|
- Step 3 (Navigate): 1 minute
|
|
- Step 4 (Generate key): 1 minute
|
|
- Configure script: 2 minutes
|
|
|
|
---
|
|
|
|
## ✨ After You Have the Key
|
|
|
|
Continue with the execution guide:
|
|
|
|
```bash
|
|
cd /Users/kempersc/apps/glam
|
|
|
|
# 1. Run API harvest (1-2 hours)
|
|
python3 scripts/scrapers/harvest_archivportal_d_api.py
|
|
|
|
# 2. Cross-reference with ISIL (1 hour)
|
|
python3 scripts/scrapers/merge_archivportal_isil.py
|
|
|
|
# 3. Create unified dataset (1 hour)
|
|
python3 scripts/scrapers/create_german_unified_dataset.py
|
|
```
|
|
|
|
See `EXECUTION_GUIDE.md` for complete instructions.
|
|
|
|
---
|
|
|
|
**Last Updated**: November 19, 2025
|
|
**Verified**: Registration flow active, API key page exists at `/user/apikey`
|