glam/data/isil/germany/API_KEY_GUIDE.md

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:

cd /Users/kempersc/apps/glam
nano scripts/scrapers/harvest_archivportal_d_api.py

Edit line 21:

# 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:

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:

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