seo_research
SEO 数据。
SEO 数据。action=serp：直接返回某个关键词的 Google 自然搜索结果（约 8 秒，$0.002）。action=keyword_suggestions：返回带 search_volume、cpc、competition、difficulty 和 intent 的关键词结果（约 3 秒，约 $0.013）。action=keyword_difficulty：给出关键词的难度（约 3 秒，约 $0.012）。> location_code 取国家名（'United States'、'China'、'Hong Kong'）或数字代码，默认 US;language_code 默认 'en'。depth 控制 SERP 的深度；limit 控制关键词建议的数量。
以上是服务端发布的英文描述的译文；英文原文见英文页。工具名、参数名和取值保持原样。
| 字段 | 值 |
|---|---|
| 工具包 | SEO & AI visibility (seo) |
| 每次调用的预估成本 | ~$0.013（上游成本；各 action 的具体数字见描述） |
| 工具包每月上限 | 上游成本 $3（不向用户显示） |
| 项目 | 可选（project 或 X-OpenNomos-Project）；只是把项目 id 附在结果里 |
参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
project | 否 | string | 项目 slug 或 id。省略则用凭据或工作区的默认项目。 |
action | 是 | "serp" | "keyword_suggestions" | "keyword_difficulty" | serp = Google 自然搜索结果；keyword_suggestions = 带搜索量/cpc/难度的相关关键词；keyword_difficulty = 给定关键词的难度。 |
keyword | 否 | string | 种子关键词，例如 'ai crm'。serp 和 keyword_suggestions 使用（keyword_difficulty 也可把它当作单个关键词）。 |
keywords | 否 | string[] | 仅 keyword_difficulty：要打分的关键词，例如 ['ai crm', 'sales copilot']。 |
location_code | 否 | integer (≥ 1) | string | 从哪里搜索：国家名（如 "United States"、"China"、"Hong Kong"、"Japan"）、两位国家代码（"US"、"CN"），或数字形式的 DataForSEO 地区代码（如 2840）。默认 United States。 |
language_code | 否 | string | 搜索语言代码，例如 'en'、'de'、'ja'。默认 'en'。 |
depth | 否 | integer (≥ 1, ≤ 100) | 仅 serp：要多少条结果。默认 10。 |
limit | 否 | integer (≥ 1, ≤ 100) | 仅 keyword_suggestions：最多返回多少个关键词。默认 20。 |
示例调用
{
"action": "keyword_suggestions",
"keyword": "ai crm",
"location_code": "United States",
"limit": 20
}REST:POST https://service.opennomos.com/v1/tools/seo_research，以上 JSON 作为请求体。MCP:tools/call,name: "seo_research"，以上 JSON 作为 arguments。
示例结果
示例里的值是示意性的；结构来自服务端代码。
{
"results": [
{
"keyword": "ai crm software",
"search_volume": 5400,
"cpc": 12.4,
"competition": 0.61,
"difficulty": 38,
"intent": "commercial"
},
"…"
]
}说明
- 三个 action:
serp（Google 自然结果，约 8 秒、$0.002）、keyword_suggestions（约 3 秒、约 $0.013）和keyword_difficulty（约 3 秒、约 $0.012）。 location_code接受国家名（"United States"、"China"、"Hong Kong"）、两位国家代码（"US"、"CN"）或数字形式的 DataForSEO 代码。名称未知时，返回的错误里会列出示例。serp只返回自然结果；实际返回少于depth时，note会说明。- 每个关键词行里的具体字段名来自服务商，没有做规范化。
错误
上游出问题时，会在一个正常结果里以 error、reason 和 action 报告（适用时还有 tool / retry_after_seconds）。对 search_signals，这会按来源分别出现。见错误。
这个工具属于 SEO & AI visibility 工具包。如果该包没有启用，调用会以 pack_required（HTTP 403）失败；如果该包的每月上游成本上限已用完，会以 soft_limit（HTTP 429）失败。两者都带 action: "give_up_and_tell_user" 和控制台 URL。