Skip to content

KEYWORD_API_DOCUMENTATION.md

Latest commit

 

History

History
391 lines (327 loc) · 8.63 KB

KEYWORD_API_DOCUMENTATION.md

File metadata and controls

391 lines (327 loc) · 8.63 KB

Keyword Suggestions API Documentation

This API provides free keyword suggestions with search volume, difficulty, and competition data. It uses Google Autocomplete (100% free) and optionally DataForSEO for enhanced metrics.

Features

  • Free keyword suggestions from Google Autocomplete
  • Search volume estimation or real data (with DataForSEO)
  • Keyword difficulty calculation
  • Related keywords with variations (what, how, why, when, where)
  • Batch analysis for multiple keywords
  • Opportunity score to identify the best keywords
  • 24-hour caching for better performance

Authentication

All endpoints require authentication:

  • User Dashboard: Bearer token (Sanctum)
  • WordPress Plugin: API Key in X-API-KEY header

Endpoints

1. Get Keyword Suggestions

Get keyword suggestions based on a seed keyword.

Endpoint: POST /api/keywords/suggestions

Request:

{
  "keyword": "seo tools",
  "country": "us",
  "language": "en",
  "limit": 20
}

Parameters:

  • keyword (required): The seed keyword (2-255 characters)
  • country (optional): 2-letter country code (default: "us")
  • language (optional): 2-letter language code (default: "en")
  • limit (optional): Number of results (1-100, default: 20)

Response:

{
  "success": true,
  "data": {
    "keyword": "seo tools",
    "suggestions": [
      {
        "keyword": "seo tools free",
        "search_volume": 8100,
        "difficulty": 45,
        "cpc": 2.50,
        "competition": 0.65,
        "source": "google_autocomplete"
      },
      {
        "keyword": "best seo tools",
        "search_volume": 5400,
        "difficulty": 52,
        "cpc": 3.20,
        "competition": 0.72,
        "source": "google_autocomplete"
      }
    ],
    "total": 20
  }
}

2. Get Related Keywords

Get related keywords with variations (prefixes and suffixes).

Endpoint: POST /api/keywords/related

Request:

{
  "keyword": "content marketing",
  "country": "us",
  "language": "en",
  "limit": 50
}

Response:

{
  "success": true,
  "data": {
    "keyword": "content marketing",
    "related_keywords": [
      {
        "keyword": "what is content marketing",
        "search_volume": 12000,
        "difficulty": 38,
        "cpc": 1.80,
        "competition": 0.55,
        "source": "google_autocomplete"
      },
      {
        "keyword": "how to do content marketing",
        "search_volume": 3200,
        "difficulty": 42,
        "cpc": 2.10,
        "competition": 0.60,
        "source": "google_autocomplete"
      }
    ],
    "total": 50
  }
}

3. Analyze Keyword

Analyze a specific keyword with detailed metrics and recommendations.

Endpoint: POST /api/keywords/analyze

Request:

{
  "keyword": "email marketing",
  "country": "us",
  "language": "en"
}

Response:

{
  "success": true,
  "data": {
    "keyword": "email marketing",
    "search_volume": 22000,
    "difficulty": 65,
    "cpc": 5.40,
    "competition": 0.82,
    "opportunity_score": 48,
    "recommendation": "Good opportunity - Moderate effort required",
    "related_keywords": [
      {
        "keyword": "email marketing software",
        "search_volume": 8900,
        "difficulty": 58,
        "cpc": 6.20,
        "competition": 0.78,
        "source": "google_autocomplete"
      }
    ]
  }
}

Opportunity Score:

  • 70-100: Excellent opportunity - High volume with low competition
  • 50-69: Good opportunity - Moderate effort required
  • 30-49: Consider targeting - May require significant effort
  • 0-29: Low opportunity - Consider alternative keywords

4. Batch Analyze Keywords

Analyze multiple keywords at once and get them sorted by opportunity.

Endpoint: POST /api/keywords/batch-analyze

Request:

{
  "keywords": [
    "seo audit",
    "keyword research",
    "backlink analysis",
    "content optimization"
  ],
  "country": "us",
  "language": "en"
}

Response:

{
  "success": true,
  "data": {
    "results": [
      {
        "keyword": "keyword research",
        "search_volume": 18000,
        "difficulty": 48,
        "opportunity_score": 72,
        "recommendation": "Excellent opportunity - High volume with low competition",
        "related_keywords": [...]
      },
      {
        "keyword": "seo audit",
        "search_volume": 12000,
        "difficulty": 55,
        "opportunity_score": 58,
        "recommendation": "Good opportunity - Moderate effort required",
        "related_keywords": [...]
      }
    ],
    "total": 4,
    "best_opportunity": {
      "keyword": "keyword research",
      "opportunity_score": 72
    }
  }
}

5. Clear Cache

Clear cached keyword data.

Endpoint: POST /api/keywords/clear-cache

Request:

{
  "keyword": "seo tools"  // Optional - clears specific keyword, omit to clear all
}

Response:

{
  "success": true,
  "message": "Cache cleared for keyword: seo tools"
}

Data Sources

Google Autocomplete (Free)

  • No API key required
  • Provides keyword suggestions
  • No built-in metrics

DataForSEO (Optional)

  • Free tier available: https://dataforseo.com/
  • Provides real search volume, competition, and CPC data
  • Add credentials to .env: 
    DATAFORSEO_LOGIN=your_login
DATAFORSEO_PASSWORD=your_password

Estimated Metrics (Fallback)

When DataForSEO is not configured, the API provides estimated metrics:

  • Search volume based on keyword position and length
  • Difficulty calculated from keyword characteristics
  • CPC and competition randomized within realistic ranges
  • Marked with "source": "estimated"

Country Codes

Supported countries:

  • us - United States (default)
  • uk - United Kingdom
  • ca - Canada
  • au - Australia
  • de - Germany
  • fr - France
  • es - Spain
  • it - Italy
  • nl - Netherlands
  • br - Brazil
  • in - India
  • mx - Mexico
  • jp - Japan
  • cn - China

Rate Limiting

  • Results are cached for 24 hours
  • Use the cache wisely to avoid unnecessary API calls
  • DataForSEO free tier has limits - check their documentation

Error Handling

Validation Error (422):

{
  "success": false,
  "message": "Validation error",
  "errors": {
    "keyword": ["The keyword field is required."]
  }
}

Server Error (500):

{
  "success": false,
  "message": "Failed to fetch keyword suggestions",
  "error": "Internal server error"
}

Example Usage with cURL

Get Suggestions

curl -X POST https://your-domain.com/api/keywords/suggestions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "digital marketing",
    "country": "us",
    "limit": 10
  }'

Analyze Keyword

curl -X POST https://your-domain.com/api/keywords/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "social media marketing"
  }'

WordPress Plugin (with API Key)

curl -X POST https://your-domain.com/api/ai/keywords/suggestions \
  -H "X-API-KEY: your_wordpress_site_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "wordpress seo",
    "limit": 15
  }'

Best Practices

  1. Use caching: Results are cached for 24 hours. Use the same parameters to benefit from cache.

  2. Batch requests: Use batch-analyze for multiple keywords instead of individual requests.

  3. Start broad, then narrow: Use suggestions → related → analyze workflow.

  4. Target high opportunity keywords: Focus on keywords with opportunity score > 50.

  5. Consider long-tail keywords: Usually easier to rank (lower difficulty).

Integration with WeGenius

The keyword API is integrated with your content analysis workflow:

  1. Research Phase: Get keyword suggestions before writing
  2. Optimization: Analyze keywords to optimize existing content
  3. Plugin Integration: WordPress plugin can fetch keywords via API key
  4. Dashboard: Full access via Sanctum authentication

Setup Instructions

  1. No additional setup required for basic functionality (Google Autocomplete)

  2. Optional - Enable DataForSEO:

    • Sign up at https://dataforseo.com/
    • Get your login and password
    • Add to .env: 
      DATAFORSEO_LOGIN=your_login
DATAFORSEO_PASSWORD=your_password

  3. Test the API:

    php artisan tinker

$service = app(\App\Services\KeywordSuggestionService::class);
$results = $service->getSuggestions('test keyword');
dd($results);

Support

For issues or questions:

  • Check Laravel logs: storage/logs/laravel.log
  • Enable debug mode: APP_DEBUG=true in .env
  • Review API responses for detailed error messages