接口参考 · 查询操作
关键词建议
taobao.universalbp.new.bidword.suggestkrlist
核对日期:2026-09-19。字段名称、类型与业务层级按淘宝文档整理;请求地址、鉴权和店铺选择按下方本站说明接入。
文档按上述日期核对;最新变更及详细场景规则请查看淘宝官方说明。
通过奇门云调用
- 签名地址:POST https://api.miandanni.com/api/wanxiang/sign;Content-Type: application/json。
- 客户购买的奇门云密钥用于申请签名;实际调用淘宝开放平台万相台官方 API。方法、字段、类型、层级、金额单位和场景以官方文档为准。奇门云校验客户服务、店铺归属与授权后签名,客户服务器直接请求淘宝并接收业务数据。
- 先下载 https://api.miandanni.com/examples/qimenyun_direct.py 放在业务脚本同目录,使用 Client.call。奇门云密钥不是淘宝 AppSecret;不要求客户自行计算平台签名。
- 签名申请头 Authorization: Bearer 你的奇门云密钥。JSON 为 {shopKey, method, params};shopKey 必须属于当前客户。客户 Bearer 密钥不能转发到淘宝。
- 业务参数放入 params,保留淘宝字段名、类型、层级及枚举。对象直接使用 JSON 对象;下表业务根字段不放在请求最外层。
- app_key、session、sign、timestamp、v、format 等公共字段由服务器生成。签发的本店铺 session 和签名只能用于客户服务器,不进入前端、日志或公共仓库;AppSecret 和 refresh_token 不提供给客户。
- 本站支持店铺直接登录:top_service_context.login_type 为 1,ext 为 {} 或字符串 "{}";不允许 member_id、其他账户身份或代理登录。官方表内此类字段用于说明差异,不能照抄传入。
- 业务根对象未填写的必填子项需按官方文档补全。ID 保持精度,金额单位、日期范围和枚举以具体方法官方说明为准。
- 签发成功为 {ok:true,data:{version:1,ticketId,service,method,issuedAt,request}},不表示业务已执行;客户端按合同执行 data.request。TOP fields 原样作为字符串表单发送,不改值。
- 淘宝业务响应直接返回客户程序,保留 error_response、top_result、逐项错误和 request_id;HTTP 200 仍检查 top_result.info.ok。签名阶段失败读取奇门云 error.code、message 和 details。
- 每次签名校验密钥、服务有效期、店铺归属、淘宝应用订购及授权。业务能力仍取决于淘宝资格与推广场景。签发限流不等于平台实际调用次数。
- 一次签名只生成一份请求,不自动翻页或重试。创建、调价、启停、删除会实际生效;超时或结果未知先查询实际状态。ticketId 不是平台幂等键。
- 签名不是一次性凭据,平台接受的时间窗口内可能重放;解绑、停用或到期阻止新签发,不能即时撤回已签发请求。老客户原程序继续可用。
- 每周一北京时间凌晨2:00检查官方更新,经核对验证后同步,不承诺实时同步。官方方法尚未同步时提供完整方法名和官方链接反馈,不误判为平台权限不足。
{
"shopKey": "填写你授权店铺的 shopKey",
"method": "taobao.universalbp.new.bidword.suggestkrlist",
"params": {
"top_service_context": {
"biz_code": "universalBP",
"login_type": 1,
"ext": "{}"
},
"bidword_suggest_query_v_o": {}
}
}这是请求结构模板。空对象和占位内容需按下方字段表填写;修改接口未填入任何真实广告编号或预算。
请求业务参数
以下路径都位于请求体的 params 内。[] 表示数组元素;嵌套字段的必填标记只描述其父对象使用时的要求。
官方 top_service_context.member_id、代理登录和扩展身份不适用于本站。本站固定使用自己的已授权店铺,login_type=1、ext={}。
| 字段路径 | 类型 / 必填 | 字段含义 | 示例值 |
|---|---|---|---|
top_service_context | TopServiceContext必填含下级字段 | 推广业务上下文 | — |
top_service_context.biz_code | String必填 | 推广场景标识 | xxxxx |
top_service_context.login_type | Number可选 | 账户登录方式枚举:1、2=代理直投(叉乘账号) | 1 |
top_service_context.member_id | Number可选 | 广告账户标识代理直投(叉乘)时必填 | 12345 |
top_service_context.ext | String可选 | 扩展参数 | {} |
bidword_suggest_query_v_o | BidwordSuggestQueryVO必填含下级字段 | 关键词建议查询 | — |
bidword_suggest_query_v_o.type | String可选 | 类型枚举:kr_overall=综合推荐、kr_flow=精准引流、kr_category=类目优质词、kr_industry=行业机会词、kr_mta=助攻词、kr_search=搜索词联想、kr_byword=以词推词、kr_bycrowd=以人群词、new_default=新建流程默认推词 | kr_overall |
bidword_suggest_query_v_o.material_id | Number可选 | 素材标识 | 715017855321 |
bidword_suggest_query_v_o.adgroup_id | Number可选 | 推广单元编号单元已经存在场景必填 | 68793666608 |
bidword_suggest_query_v_o.campaign_id | Number可选 | 推广计划编号计划已经存在场景必填 | 68796878069 |
bidword_suggest_query_v_o.word | String可选 | 词 | 连衣裙 |
bidword_suggest_query_v_o.crowd_id_list | Number []可选 | 人群标识列表 | [111] |
返回业务字段
响应外层为 universalbp_new_bidword_suggestkrlist_response。下面的逻辑字段路径从该外层内部开始;样例 JSON 路径额外标注 TOP 集合包装,解析时仍需以实际返回为准。
| 字段路径 | 类型 / 必填 | 字段含义 | 示例值 |
|---|---|---|---|
top_result样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result | TopResult官方未标注必填含下级字段 | 接口业务结果 | — |
top_result.info样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.info | TopInfo官方未标注必填含下级字段 | 执行状态信息 | — |
top_result.info.ok样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.info.ok | Boolean官方未标注必填 | 业务是否成功 | true |
top_result.info.message样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.info.message | String官方未标注必填 | 业务结果提示 | 参数错误 |
top_result.info.error_code样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.info.error_code | String官方未标注必填 | 业务错误标识 | xxxxx |
top_result.suggest_bidword_v_o_top_bulk_data样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data | TopBulkData官方未标注必填含下级字段 | 建议关键词对象 | — |
top_result.suggest_bidword_v_o_top_bulk_data.count样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.count | Number官方未标注必填 | 结果计数 | 10 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list | SuggestBidwordVO []官方未标注必填含下级字段 | 建议关键词列表 | — |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].word样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].word | String官方未标注必填 | 词 | 吵吵家 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].bid_price样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].bid_price | String官方未标注必填 | 出价金额 | 1 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].avg_price样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].avg_price | String官方未标注必填 | 业务字段 avg_price | 0.47 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].impression样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].impression | String官方未标注必填 | 业务字段 impression | 0-10 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].relevance_type样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].relevance_type | Number官方未标注必填 | 业务字段 relevance_type枚举:1=差、2=中、3=好 | 3 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].ctr样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].ctr | String官方未标注必填 | 点击比例 | 0.0381 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].cvr样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].cvr | String官方未标注必填 | 转化比例 | 0.0209 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].impression_index样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].impression_index | Number官方未标注必填 | 业务字段 impression_index | 30 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].competition_index样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].competition_index | String官方未标注必填 | 业务字段 competition_index | 20 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].search_index样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].search_index | Number官方未标注必填 | 业务字段 search_index | 20 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].qscore样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].qscore | String官方未标注必填 | 业务字段 qscore | 6.00 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].item_click样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].item_click | Number官方未标注必填 | 业务字段 item_click | 20 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].transaction_shipping_total样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].transaction_shipping_total | Number官方未标注必填 | 业务字段 transaction_shipping_total | 20 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].item_click_coverage样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].item_click_coverage | String官方未标注必填 | 业务字段 item_click_coverage | 0.5 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list | ShowTagVO []官方未标注必填含下级字段 | 列表集合 | — |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].code样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list.show_tag_v_o[].code | String官方未标注必填 | 结果或业务代码 | hign_cvr |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].name样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list.show_tag_v_o[].name | String官方未标注必填 | 对象名称 | 高转化率 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].tips样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list.show_tag_v_o[].tips | String官方未标注必填 | 业务字段 tips | xxxxxx |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].icon样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list.show_tag_v_o[].icon | String官方未标注必填 | 业务字段 icon | xxxxxx |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].color样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list.show_tag_v_o[].color | String官方未标注必填 | 业务字段 color | #FF4D4D |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].type样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].reason_tag_list.show_tag_v_o[].type | String官方未标注必填 | 类型 | display_ocpc |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].reason_tag_list[].properties | String官方未标注必填 | 扩展属性内容 | — |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].type样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].type | Number官方未标注必填 | 类型枚举:0=宝贝、1=店铺 | 0 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].mta_roi样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].mta_roi | String官方未标注必填 | 业务字段 mta_roi | 20 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].predict_click样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].predict_click | String官方未标注必填 | 业务字段 predict_click | 0.029 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].market_click_rate样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].market_click_rate | String官方未标注必填 | 业务字段 market_click_rate | 0.029 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].market_average_bid样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].market_average_bid | String官方未标注必填 | 业务字段 market_average_bid | 0.029 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].market_click_conversion_rate样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].market_click_conversion_rate | String官方未标注必填 | 业务字段 market_click_conversion_rate | 0.29 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].first_slot_impression_rate样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].first_slot_impression_rate | String官方未标注必填 | 业务字段 first_slot_impression_rate | 0.29 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].lead_ad_gmv_rate样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].lead_ad_gmv_rate | String官方未标注必填 | 业务字段 lead_ad_gmv_rate | 0.046 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].trend_index样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].trend_index | String官方未标注必填 | 业务字段 trend_index | 0.046 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].present_m_penetration_rate样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].present_m_penetration_rate | String官方未标注必填 | 业务字段 present_m_penetration_rate | 0.46 |
top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list[].rec_reason样例 JSON:universalbp_new_bidword_suggestkrlist_response.top_result.suggest_bidword_v_o_top_bulk_data.suggest_bidword_v_o_list.suggest_bidword_v_o[].rec_reason | String官方未标注必填 | 业务字段 rec_reason | 热门词 |
字段核对说明
- 部分响应字段未出现在官方 JSON 示例中;wirePath 为 null 时请依实际返回核对。
Python 签名直连示例
下载 qimenyun_direct.py 与业务脚本放在同一目录,保留淘宝业务参数,使用奇门云密钥和 shopKey 申请签名,由客户服务器直接请求淘宝。运行前补全业务参数,无需自行计算平台签名。
# Python 3.9+,无需安装第三方依赖。
# 先下载 https://api.miandanni.com/examples/qimenyun_direct.py 放在本文件同一目录。
# 先申请签名,再由本程序直接请求淘宝;业务数据直接返回客户服务器。
import json
from getpass import getpass
from qimenyun_direct import Client, CallError, check_result
api_key = getpass("请输入奇门云密钥:").strip()
config = {"mode": "direct", "apiKey": api_key, "services": {"wanxiang": {"signEndpoint": "https://api.miandanni.com/api/wanxiang/sign"}}}
client = Client(config)
body = json.loads("{\"shopKey\":\"填写你授权店铺的 shopKey\",\"method\":\"taobao.universalbp.new.bidword.suggestkrlist\",\"params\":{\"top_service_context\":{\"biz_code\":\"universalBP\",\"login_type\":1,\"ext\":\"{}\"},\"bidword_suggest_query_v_o\":{}}}")
body["shopKey"] = input("请输入自己的 shopKey:").strip()
try:
result = client.call("wanxiang", body)
print(client.display(result))
check_result(result)
except CallError as exc:
print(client.display(exc.payload))
raise SystemExit(str(exc)) from None
# 不自动重试。写操作超时或结果未知时,先查询实际状态。
判断成功与失败
签名阶段先检查 HTTP 状态;本站鉴权、套餐或授权失败返回 {ok:false,error:{code,message}}。签名 HTTP 200 仅说明已签发;客户端执行官方请求后,还要检查淘宝响应的 error_response、逐项错误和 top_result.info.ok;失败不能当成空列表。
执行阶段的淘宝原始 error_response、业务 info 和 request_id 直接返回客户服务器,不由奇门云统一包装。签名和授权由本站管理,业务参数、日期、分页及平台资格按淘宝原始错误排查。
error_response:TOP 网关错误;应读取错误码及细分错误码,不能按空结果处理。top_result.info:HTTP 成功仍须核对业务 ok;false 表示业务未完成。
下载本页 MD 可交给开发人员或 AI,密钥只填在自己的私密配置中。