# Generate keyword budget estimate

Creates a comprehensive budget estimate for organic keywords based on SEMRush data analysis.

The API will:
1. Retrieve organic keyword data
2. Calculate budget estimates with trend analysis
3. Provide recommendations and value scores
4. Cache results for 24 hours to optimize costs


- Results are cached for 24 hours based on request parameters
- Cached responses include  flag
- Fresh API calls include  flag


Endpoint: POST /api/v1/keywords/budget/estimate
Version: 2.0.0
Security: JWTAuth

## Request fields (application/json):

  - `url` (string, required)
    Client business domain URL to analyze
    Example: "https://example.com"

  - `categories` (array)
    Business categories for keyword filtering
    Example: ["+|Ph|Co|seo","technology","software"]

  - `seeds` (array)
    Seed keywords to guide the analysis
    Example: ["seo tools","keyword research","digital marketing"]

  - `market` (string)
    Country/locale code for market analysis
    Example: "us"

  - `language` (string)
    Language code for analysis
    Example: "en"

  - `max_keywords` (integer)
    Maximum number of keywords to return
    Example: 50

## Response 200 fields (application/json):

  - `data` (object)

  - `data.url` (string)
    Analyzed domain URL
    Example: "https://example.com"

  - `data.market` (string)
    Market used for analysis
    Example: "us"

  - `data.language` (string)
    Language used for analysis
    Example: "en"

  - `data.total_keywords` (integer)
    Total number of keywords found
    Example: 25

  - `data.keywords` (array)

  - `data.keywords.keyword` (string)
    The keyword phrase
    Example: "seo tools"

  - `data.keywords.position` (string)
    Current search engine position
    Example: "5"

  - `data.keywords.previous_position` (string)
    Previous position
    Example: "7"

  - `data.keywords.position_difference` (string)
    Position change
    Example: "2"

  - `data.keywords.monthly_searches` (string)
    Monthly search volume
    Example: "1200"

  - `data.keywords.cpc` (string)
    Cost per click
    Example: "2.50"

  - `data.keywords.url` (string)
    Landing page URL
    Example: "https://example.com/seo-tools"

  - `data.keywords.traffic` (string)
    Estimated monthly traffic
    Example: "45.20"

  - `data.keywords.traffic_cost` (string)
    Estimated traffic cost
    Example: "113.00"

  - `data.keywords.competition` (string)
    Competition level (0-1)
    Example: "0.45"

  - `data.keywords.number_of_results` (string)
    Number of search results
    Example: "12500000"

  - `data.keywords.monthly_trends` (array)
    12-month trend data
    Example: ["0.29","0.23","0.23","0.44","0.36","0.36","0.36","0.54","0.66","0.81","1.00","0.66"]

  - `data.keywords.current_trend` (number)
    Most recent trend value
    Example: 0.66

  - `data.keywords.trend_summary` (object)

  - `data.keywords.trend_summary.direction` (string)
    Trend direction
    Enum: "accelerating", "decelerating", "stable"

  - `data.keywords.trend_summary.strength` (string)
    Trend strength
    Enum: "Very High", "High", "Moderate", "Low", "Very Low"

  - `data.keywords.trend_summary.category` (string)
    Trend category
    Enum: "exploding", "rising", "growing", "stable", "declining", "falling", "crashing"

  - `data.keywords.trend_summary.description` (string)
    Human-readable trend description
    Example: "Strong upward trend - good opportunity"

  - `data.keywords.trend_summary.average_trend` (number)
    Average trend value
    Example: 0.57

  - `data.keywords.trend_summary.trend_strength` (number)
    Trend strength value
    Example: 0.77

  - `data.keywords.trend_summary.peak_month` (number)
    Peak trend value
    Example: 1

  - `data.keywords.trend_summary.lowest_month` (number)
    Lowest trend value
    Example: 0.23

  - `data.keywords.budget_estimate` (object)

  - `data.keywords.budget_estimate.monthly_budget` (string)
    Recommended monthly budget
    Example: "25.00"

  - `data.keywords.budget_estimate.quarterly_budget` (string)
    Recommended quarterly budget
    Example: "75.00"

  - `data.keywords.budget_estimate.yearly_budget` (string)
    Recommended yearly budget
    Example: "300.00"

  - `data.keywords.budget_estimate.cost_per_acquisition` (string)
    Cost per acquisition
    Example: "0.02"

  - `data.keywords.budget_estimate.value_score` (integer)
    Value score (1-5)
    Example: 3

  - `data.keywords.budget_estimate.value_description` (string)
    Value description
    Enum: "Low Value", "Budget-Friendly", "Moderate Value", "High Value", "Premium Value"

  - `data.keywords.budget_estimate.recommendation` (string)
    Budget recommendation
    Example: "Good opportunity - trending upward with reasonable budget"

  - `data.estimated_budget` (object)

  - `data.estimated_budget.total_keywords` (integer)
    Total keywords analyzed
    Example: 25

  - `data.estimated_budget.total_monthly_searches` (string)
    Total monthly search volume
    Example: "18000"

  - `data.estimated_budget.average_cpc` (string)
    Average cost per click
    Example: "10.54"

  - `data.estimated_budget.total_traffic_cost` (string)
    Total estimated traffic cost
    Example: "79.09"

  - `data.estimated_budget.average_competition` (string)
    Average competition level
    Example: "0.049"

  - `data.estimated_budget.estimated_monthly_budget` (string)
    Estimated monthly budget
    Example: "27.68"

  - `data.estimated_budget.estimated_quarterly_budget` (string)
    Estimated quarterly budget
    Example: "83.04"

  - `data.estimated_budget.estimated_yearly_budget` (string)
    Estimated yearly budget
    Example: "332.18"

  - `data.cached` (boolean)
    Whether data was served from cache

  - `data.cache_timestamp` (string)
    Cache timestamp
    Example: "2024-01-15T14:30:25Z"

  - `data.debug_info` (object)
    Debug information for empty results

  - `data.debug_info.reason` (string)
    Example: "No keywords found for this domain"

  - `data.debug_info.possible_causes` (array)
    Example: ["Domain is too new or has insufficient organic traffic"]

  - `data.debug_info.api_parameters` (object)

  - `data.debug_info.api_parameters.market` (string)
    Example: "us"

  - `data.debug_info.api_parameters.language` (string)
    Example: "en"

  - `data.debug_info.api_parameters.max_keywords` (integer)
    Example: 50

  - `message` (string)
    Response message
    Example: "Budget estimate generated successfully."

  - `error_code` (string)
    Error code (empty for success)

  - `status_code` (integer)
    HTTP status code
    Example: 200

## Response 400 fields (application/json):

  - `data` (object)
    Empty data object

  - `message` (array)
    Validation error messages
    Example: ["Please enter a client business domain URL."]

  - `error_code` (string)
    Error code
    Example: "validation-error"

  - `status_code` (integer)
    HTTP status code
    Example: 400

## Response 401 fields (application/json):

  - `data` (object)
    Empty data object

  - `message` (string)
    Error message
    Example: "Authentication required"

  - `error_code` (string)
    Error code
    Example: "auth-required"

  - `status_code` (integer)
    HTTP status code
    Example: 401

## Response 500 fields (application/json):

  - `data` (object)
    Empty data object

  - `message` (string)
    Error message
    Example: "An error occurred while generating the budget estimate: SEMRush API timeout"

  - `error_code` (string)
    Error code
    Example: "keywords-budget-estimate:2"

  - `status_code` (integer)
    HTTP status code
    Example: 500