# API Setup Guide

This guide explains how to obtain and configure all required API keys for KeywordMatcherPro.

## Required APIs

1. **OpenAI** (Required) - For AI-powered keyword extraction
2. **Jina.ai** (Required) - For clean content extraction from URLs
3. **DataForSEO** (Optional) - For search volume and keyword metrics

---

## 1. OpenAI API Setup

### Step 1: Create Account

1. Visit https://platform.openai.com/signup
2. Sign up with email or Google account
3. Verify your email address

### Step 2: Add Payment Method

1. Go to https://platform.openai.com/account/billing
2. Click "Add payment method"
3. Enter credit card details
4. Add initial credit (minimum $5 recommended)

### Step 3: Get API Key

1. Navigate to https://platform.openai.com/api-keys
2. Click "Create new secret key"
3. Give it a name: "KeywordMatcherPro"
4. Copy the key immediately (it won't be shown again!)
5. Add to `.env` file:
   ```env
   OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxx
   ```

### Cost Estimate

- Model: `gpt-4o-mini` (recommended)
- Input: $0.15 per 1M tokens
- Output: $0.60 per 1M tokens
- **Average: $0.15 per 100 pages**

### Rate Limits

- Free tier: 60 requests per minute
- Tier 1: 500 requests per minute
- Check your tier: https://platform.openai.com/account/limits

---

## 2. Jina.ai API Setup

### Step 1: Create Account

1. Visit https://jina.ai/
2. Click "Sign Up" or "Get Started"
3. Sign up with GitHub, Google, or email

### Step 2: Get API Key

1. Go to https://jina.ai/api-dashboard/
2. Click "Create API Key" or "Get API Key"
3. Copy the API key (starts with `jina_`)
4. Add to `.env` file:
   ```env
   JINA_API_KEY=jina_xxxxxxxxxxxxxxxxxxxxxxx
   ```

### Free Tier

- **500 requests per minute** (free)
- Token-based pricing after free tier
- Perfect for production use with caching

### Cost Estimate

- With 30-day caching: **~$0.10 per 100 pages**
- Without caching: ~$0.10 per 100 pages
- First analysis is free tier eligible

### Rate Limits

- Without API key: 20 RPM (IP-based)
- Free API key: 500 RPM
- Premium: 5000 RPM

---

## 3. DataForSEO API Setup (Optional)

### Step 1: Create Account

1. Visit https://app.dataforseo.com/register
2. Fill out registration form
3. Verify email address

### Step 2: Add Credits

1. Go to https://app.dataforseo.com/billing
2. Minimum payment: **$50**
3. Pay-as-you-go (no subscription)
4. Credits don't expire

### Step 3: Get API Credentials

1. Go to https://app.dataforseo.com/api-access
2. Your login is your email address
3. API password is auto-generated (different from account password)
4. Copy both credentials
5. Add to `.env` file:
   ```env
   DATAFORSEO_LOGIN=your_email@example.com
   DATAFORSEO_PASSWORD=your_api_password_here
   DATAFORSEO_ENABLED=true
   ```

### Cost Estimate

- Google Ads Search Volume: $0.025 per 1000 keywords
- **Average: $0.10 per 100 pages** (with 20 keywords per page)

### When to Use

**Use DataForSEO if:**
- You need accurate search volume data
- You want competition metrics
- You need CPC (cost-per-click) data
- Client requires hard data for keyword selection

**Skip DataForSEO if:**
- Budget is tight
- Content relevance is more important than search volume
- Testing the tool initially

### Enable/Disable

To disable DataForSEO without removing credentials:
```env
DATAFORSEO_ENABLED=false
```

The tool will still work but won't fetch search volume data. It will rely purely on AI relevance scores.

---

## Testing API Connections

After configuring all API keys, test the connections:

### Test Script

Create `test-apis.php` in the project root:

```php
<?php
require __DIR__.'/vendor/autoload.php';
$app = require_once __DIR__.'/bootstrap/app.php';
$app->make(\Illuminate\Contracts\Console\Kernel::class)->bootstrap();

echo "Testing API Connections...\n\n";

// Test Jina
echo "1. Testing Jina.ai API...\n";
try {
    $jina = new \App\Services\JinaContentExtractor();
    $content = $jina->fetchContent('https://example.com');
    echo "   ✓ Jina API: Connected\n";
    echo "   Content length: " . strlen($content) . " characters\n";
} catch (\Exception $e) {
    echo "   ✗ Jina API: Failed - " . $e->getMessage() . "\n";
}

echo "\n2. Testing OpenAI API...\n";
try {
    $ai = new \App\Services\AIKeywordExtractor();
    $keywords = $ai->extractKeywords('This is a test about SEO tools and keyword research', 'product');
    echo "   ✓ OpenAI API: Connected\n";
    echo "   Keywords extracted: " . count($keywords) . "\n";
} catch (\Exception $e) {
    echo "   ✗ OpenAI API: Failed - " . $e->getMessage() . "\n";
}

echo "\n3. Testing DataForSEO API...\n";
if (config('services.dataforseo.enabled')) {
    try {
        $dataForSEO = new \App\Services\DataForSEOClient();
        $metrics = $dataForSEO->getSearchVolume(['seo tools', 'keyword research']);
        echo "   ✓ DataForSEO API: Connected\n";
        echo "   Metrics fetched: " . count($metrics) . " keywords\n";
    } catch (\Exception $e) {
        echo "   ✗ DataForSEO API: Failed - " . $e->getMessage() . "\n";
    }
} else {
    echo "   ⊘ DataForSEO: Disabled in configuration\n";
}

echo "\n✅ API connection test complete!\n";
```

Run the test:
```bash
php test-apis.php
```

---

## Environment Configuration Summary

Complete `.env` configuration for all APIs:

```env
# OpenAI (REQUIRED)
OPENAI_API_KEY=sk-proj-your-key-here
OPENAI_MODEL=gpt-4o-mini
OPENAI_TEMPERATURE=0.3
OPENAI_MAX_TOKENS=500
OPENAI_RATE_LIMIT_MS=50

# Jina.ai (REQUIRED)
JINA_API_KEY=jina_your-key-here
JINA_RATE_LIMIT_MS=100
JINA_CACHE_DAYS=30

# DataForSEO (OPTIONAL)
DATAFORSEO_LOGIN=your_email@example.com
DATAFORSEO_PASSWORD=your_api_password
DATAFORSEO_ENABLED=false
DATAFORSEO_RATE_LIMIT_MS=50

# Cache Settings
METRICS_CACHE_DAYS=7

# SEO Settings
MIN_SEARCH_VOLUME=50
DEFAULT_LOCATION_CODE=2840
DEFAULT_LANGUAGE=en
BATCH_SIZE=10
MAX_KEYWORDS_PER_PAGE=20
MAX_CONTENT_LENGTH=1000
```

---

## Troubleshooting

### OpenAI "Invalid API Key"

**Solutions:**
- Verify key starts with `sk-proj-` or `sk-`
- Check for extra spaces in `.env` file
- Regenerate key if needed
- Ensure billing is set up

### Jina.ai Rate Limit Exceeded

**Solutions:**
- Increase `JINA_RATE_LIMIT_MS` to 200 or 300
- Get free API key for 500 RPM
- Enable caching (30 days default)

### DataForSEO "Authentication Failed"

**Solutions:**
- Use email as login (not username)
- Use API password (not account password)
- Check account has credits
- Verify credentials have no extra spaces

### DataForSEO "Insufficient Funds"

**Solutions:**
- Add minimum $50 to account
- Check current balance in dashboard
- Disable DataForSEO temporarily: `DATAFORSEO_ENABLED=false`

---

## API Cost Optimization Tips

1. **Enable Caching**
   - Jina: 30 days (90%+ cost reduction on re-analysis)
   - DataForSEO: 7 days (significant savings)

2. **Rate Limiting**
   - Prevents hitting rate limits
   - Avoids retry costs
   - Already configured in `.env.example`

3. **Smart Batching**
   - DataForSEO: Up to 1000 keywords per request
   - Reduces API call overhead

4. **Start Without DataForSEO**
   - Test the tool first
   - Evaluate if search volume data is necessary
   - Enable only when needed

5. **Monitor Usage**
   - Check `api_usage_logs` table
   - Track daily costs
   - Set budget alerts

---

## Support Resources

- **OpenAI**: https://help.openai.com/
- **Jina.ai**: https://discord.jina.ai/
- **DataForSEO**: support@dataforseo.com

For application-specific issues, check `storage/logs/laravel.log`