Semrush 关键词单笔入库
单笔写入一条 Semrush 关键词(可选带排名 URL)。处理规则与 /admin/file-upload 上传「Semrush关键词Excel」后台异步导入一致:按 keyword 唯一;仅当新 timestamp 的日期比库内更新才覆盖指标;同时提供 url+position 时写入 seo_websites / seo_domain。
POST /api/admin/seo-ranking/ingest与批量上传的关系
Excel 异步任务会对每一行做字段映射、时间戳比较、关键词 upsert,排名格式再写域名与网站排名。本接口对单行执行相同逻辑。
- 必需:Keyword(或 keyword)
- 已存在且新日期不更新 →
skipped(不改指标) - 已存在且日期更新 → 只覆盖有值且变化的字段 →
updated - 不存在 →
created - 同时有 URL + Position → 同步处理 seo_domain / seo_websites
认证
Authorization: Bearer <API_KEY> 或登录态 Token;亦可 X-API-Key。
请求示例:纯关键词(keyword 格式)
POST /api/admin/seo-ranking/ingest
Authorization: Bearer <API_KEY>
Content-Type: application/json
{
"keyword": "ai image upscaler",
"searchVolume": 2400,
"keywordDifficulty": 38,
"cpc": 1.25,
"keywordIntents": "commercial",
"trends": "12,18,22,30,28,35,40",
"timestamp": "2026-11-17"
}请求示例:带排名(ranking 格式)
{
"keyword": "ai image upscaler",
"searchVolume": 2400,
"keywordDifficulty": 38,
"cpc": 1.25,
"timestamp": "2026-11-17",
"url": "https://example.com/tools/upscaler",
"position": 7,
"previousPosition": 12,
"traffic": 320,
"trafficPercentage": 4.5,
"trafficCost": 88.2
}也可用 Excel 原始列名
{
"Keyword": "ai image upscaler",
"Volume": 2400,
"Keyword Difficulty": 38,
"CPC (USD)": 1.25,
"Intent": "commercial",
"Trends": "12,18,22,30,28,35,40",
"Timestamp": "2026-11-17"
}响应
{
"success": true,
"data": {
"action": "created",
"keywordId": 99881,
"keyword": "ai image upscaler",
"format": "keyword_format",
"website": null
}
}关键词 action:created|updated|skipped。 若写入排名,website.action 同为 created / updated / skipped。
MCP
工具名 ingest_semrush_keyword,参数使用 camelCase(keyword / searchVolume / url / position 等)。
