Skip to main content

​
Endpoint

POST https://data.semust.com/v1/keyword-data

​
Authentication

All requests require authentication headers. See Authentication for details.
HeaderTypeDescription
SEMUST-API-USERstringYour API username
SEMUST-API-PASSWORDstringYour API password

​
Request Parameters

Send parameters as JSON in the request body with Content-Type: application/json.
ParameterTypeRequiredDefaultDescription
keywordstringYes—The keyword to analyze
countrystringNo"US"Country code (e.g., “US”, “GB”, “DE”)
languagestringNo"en"Language code (e.g., “en”, “es”, “fr”)
limitintegerNo100Maximum number of results to return

​
Code Examples

curl -X POST https://data.semust.com/v1/keyword-data \
  -H "Content-Type: application/json" \
  -H "SEMUST-API-USER: your_username" \
  -H "SEMUST-API-PASSWORD: your_password" \
  -d '{
    "keyword": "seo tools",
    "country": "US",
    "language": "en",
    "limit": 100
  }'

​
Example Response

{
  "success": true,
  "result_count": 3,
  "cost": 0.01,
  "data": [
    {
      "keyword": "seo tools",
      "search_volume": 12100,
      "cpc": 15.75,
      "competition": 85,
      "competition_level": "high",
      "country": "us",
      "language": "en",
      "intent": "commercial",
      "related_keywords": ["best seo tools", "free seo tools"]
    },
    {
      "keyword": "best seo tools",
      "search_volume": 8100,
      "cpc": 12.50,
      "competition": 72,
      "competition_level": "high",
      "country": "us",
      "language": "en",
      "intent": "commercial",
      "related_keywords": null
    },
    {
      "keyword": "free seo tools",
      "search_volume": 5400,
      "cpc": 8.25,
      "competition": 45,
      "competition_level": "medium",
      "country": "us",
      "language": "en",
      "intent": "informational",
      "related_keywords": null
    }
  ]
}
Results are sorted by search volume (highest to lowest). Related keywords may be null if not available for a particular keyword.

​
Response Fields

​
Top-Level Response

FieldTypeDescription
successbooleanAlways true on successful requests
result_countintegerNumber of keywords returned
costfloatCost in USD for this request
dataarrayArray of keyword data objects

​
Keyword Data Object

FieldTypeDescription
keywordstringThe keyword term
search_volumeintegerMonthly search volume
cpcfloatCost per click (advertising)
competitionfloatCompetition level (0-100 scale)
competition_levelstringText representation: “low”, “medium”, “high”
countrystringCountry code
languagestringLanguage code
intentstringSearch intent: “commercial”, “informational”, “navigational”, “transactional”
related_keywordsarray | nullRelated keywords or null if not available

​
Pricing

The Keyword Data API is priced based on the number of results returned.

​
Formula

Cost = max($0.01, (result_count / 100) × $0.03)

​
Pricing Examples

ResultsCalculationCost
0-33Minimum charge$0.01
50(50/100) × $0.03$0.015
100(100/100) × $0.03$0.03
150(150/100) × $0.03$0.045
200(200/100) × $0.03$0.06

Upfront Charge

Credits are charged upfront before processing the request based on the expected result count.

Full Refund on Failures

If the API returns an error, you will receive a full refund of the charged credits.

​
Error Codes

Error Response
{
  "error": "Your account does not have enough credits",
  "code": "INSUFFICIENT_CREDITS"
}
StatusCodeDescription
400INVALID_REQUESTInvalid request format or malformed JSON
400KEYWORD_REQUIREDMissing required keyword parameter
401INVALID_API_KEYAuthentication failed - invalid credentials
401INVALID_CREDENTIALSInvalid username or password
401CREDENTIALS_EXPIREDAPI credentials have expired
402INSUFFICIENT_CREDITSYour account does not have enough credits
403IP_NOT_WHITELISTEDRequest IP is not in your whitelist
429RATE_LIMIT_EXCEEDEDToo many requests, please slow down
500INTERNAL_ERRORServer-side error occurred
502WORKER_FAILEDBackend worker failed to process request
504TIMEOUTRequest timed out

​
Credits & Rate Limits

Credits

Each Keyword Data request consumes credits from your account balance based on the pricing formula above.

Rate Limits

API requests are rate-limited to ensure fair usage. Contact support if you need higher limits.