Keyword Research

Discover high-opportunity keywords with competition scores, trend data, and long-tail phrases.

POST /api/v1/research/keywords

Research keywords for a given topic. Returns trending terms, competition scores, trend directions, long-tail phrases, and top competing videos. When no topic is provided, Soke automatically uses keywords extracted from your connected YouTube channel.

Credits: 2 per request

Authentication

X-Soke-Key: sk_live_your_api_key

Authorization: Bearer your_jwt_token

Request Body

Field	Type	Required	Default	Description
`topic`	string	No	—	The topic or keyword to research. Omit to use your connected channel's keywords.
`platform`	string	No	`"youtube"`	Target platform
`niche`	string	No	—	Content niche for additional context
`region`	string	No	`"US"`	Region code for localized results
`maxResults`	integer	No	`20`	Maximum keywords to return (1–50)
`recencyDays`	integer	No	`365`	Only analyse content published within this many days. Range: 1–3650.

When topic is omitted or empty, Soke automatically extracts keywords from your connected YouTube channel's top-performing videos (tags and titles). Channel keywords are cached for 6 hours for fast responses. If no channel is connected and no topic is provided, the endpoint returns a TOPIC_REQUIRED error.

Results are filtered to the last 12 months by default to ensure you see current competition data. Pass recencyDays to widen or narrow the window (e.g., 30 for the last month, 730 for the last two years).

Example Requests

With a topic

curl -X POST https://api.usesoke.ai/api/v1/research/keywords \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{
    "topic": "productivity tips for developers",
    "platform": "youtube",
    "recencyDays": 180
  }'

Without a topic (channel auto-detect)

curl -X POST https://api.usesoke.ai/api/v1/research/keywords \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{}'

Response

200 OK

{
  "success": true,
  "data": {
    "topic": "productivity tips for developers",
    "keywords": [
      {
        "keyword": "productivity tips for developers",
        "searchVolume": 8,
        "competitionScore": 0.342,
        "trendDirection": "rising",
        "isLongTail": true,
        "relatedTerms": [
          "developer productivity hacks",
          "coding productivity",
          "time management for programmers"
        ]
      },
      {
        "keyword": "developer productivity hacks",
        "searchVolume": 5,
        "competitionScore": 0.218,
        "trendDirection": "rising",
        "isLongTail": true,
        "relatedTerms": []
      }
    ],
    "longTailPhrases": [
      "productivity tips for developers 2024",
      "best productivity tips for software developers"
    ],
    "topCompetingVideos": [
      {
        "title": "10 Productivity Tips Every Developer Needs",
        "channelTitle": "Tech With Tim",
        "viewCount": 524000,
        "publishedAt": "2024-08-15T14:00:00Z",
        "description": "In this video I share my top productivity tips...",
        "tags": ["productivity", "developer", "coding"],
        "viewVelocity": 1200.5
      }
    ],
    "dataSources": "YouTube Suggest API, YouTube Data API v3, Google Trends"
  },
  "meta": {
    "platform": "youtube",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_time_ms": 1850
  }
}

Response Fields

Field	Type	Description
`topic`	string	The researched topic (may differ from input if auto-detected from channel)
`keywords`	array	Keyword results sorted by opportunity (low competition first)
`keywords[].keyword`	string	The keyword or phrase
`keywords[].searchVolume`	integer \| null	Estimated relative search volume
`keywords[].competitionScore`	number	Competition score from 0 (low) to 1 (high)
`keywords[].trendDirection`	string	`"rising"`, `"falling"`, or `"stable"`
`keywords[].isLongTail`	boolean	Whether the keyword has 4+ words
`keywords[].relatedTerms`	string[]	Related keyword suggestions
`longTailPhrases`	string[]	Long-tail phrases extracted from results
`topCompetingVideos`	array	Top 5 competing videos by view count
`topCompetingVideos[].viewVelocity`	number	Average views per day since publish
`dataSources`	string	Data sources used for the analysis

Error Codes

Code	Status	Description
`TOPIC_REQUIRED`	400	No topic provided and no YouTube channel connected
`BAD_REQUEST`	400	Invalid parameters (e.g., topic exceeds 200 characters)
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`INSUFFICIENT_CREDITS`	402	Not enough credits
`PLATFORM_NOT_IMPLEMENTED`	501	Platform not yet supported

On this page