获取搜索广告推广系列的健康状况诊断
您可以使用本接口获取搜索广告推广系列中广告组或广告的健康状况诊断信息，包括搜索量、关键词相关性以及出价和预算建议。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/tool/diagnosis/search/health/
方法 GET
Header
| 字段{30%} | 类型{15%} | 描述{55%} |
| --- | --- | --- |
| Access-Token {必填} | string | 授权访问令牌。可以通过[获取访问令牌](1738373164380162.html)接口获取。 |
参数
| 字段{30%} | 类型{15%} | 描述{55%} |
| --- | --- | --- |
| advertiser_id {必填} | string | 广告主 ID。 |
| adgroup_id | string | 广告组 ID。<br>若要获取现有广告组的诊断信息，需指定此字段。<br><br>若要获取搜索广告推广系列中的广告组 ID，可使用 [/adgroup/get/](1739314558673922.html) 接口，并将筛选条件字段 `campaign_ids` 设置为搜索广告推广系列的 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若同时指定 `adgroup id` 和 `ad_ids`，`adgroup id`将被忽略。</li></ul></p> |
| ad_ids | string[] | 广告 ID 列表。<br>若要获取现有广告的诊断信息，需指定此字段。<br><br>广告 ID 均需属于同一广告组。<br><br>最大数量：50。<br><br>若要获取搜索广告组中的广告 ID，可使用 [/ad/get/](1735735588640770.html) 接口，并将筛选条件字段 `adgroup_ids` 设置为搜索广告推广系列中搜索广告组的 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若同时指定 `adgroup id` 和 `ad_ids`，`adgroup id`将被忽略。</li></ul></p> |
示例
获取现有广告组的诊断
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/tool/diagnosis/search/health/?advertiser_id={{advertiser_id}}&adgroup_id={{adgroup_id}}' \
--header 'Access-Token: {{Access-Token}}'
(/code)
获取现有广告的诊断
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/tool/diagnosis/search/health/?advertiser_id={{advertiser_id}}&ad_ids=[{{ad_id}},{{ad_id}}]' \
--header 'Access-Token: {{Access-Token}}'
(/code)
返回
| 字段{30%} | 类型{15%} | 描述{55%} |
| --- | --- | --- |
| code | number | 返回码。完整返回码列表及描述参见[附录 - 返回码](1737172488964097.html)。 |
| message | string | 返回信息。更多信息参见[附录 - 返回码](1737172488964097.html)。 |
| request_id | string | 请求的日志 ID，唯一标识一个请求。 |
| data | object | 返回数据。 |
#| search_health_status | string | 整体搜索健康状况。此字段对广告组或广告的设置情况的概述。<br>枚举值：<ul><li>`GOOD`：良好。您的设置有助于提升广告成效。</li><li>`NEED_IMPROVEMENT`：需要改进。</li><li>`NO_DATA`：暂无数据。</li></ul> |
#| search_volume | object | 关键词搜索量的详细指标。 |
##| diagnosis_result | string | 搜索量分析的结果。<br><br>枚举值：<ul><li>`HIGH`：高。</li><li>`MEDIUM`：中。</li><li>`LOW`：低。</li><li>`INVALID`：无效。</li></ul> |
##| total_monthly_searches | number | 关键词每月获得的预估搜索次数。<br>该数值会随匹配类型的设置而有所变化。广泛匹配有助于最大化搜索量。 |
##| total_keyword_count | number | 搜索关键词总数。 |
##| total_relevant_keyword_count | number | 与广告组或广告相关的搜索关键词总数。 |
#| keyword_relevance | object[] | 关键词与广告组或广告相关性的详情。 |
##| adgroup_id | string | 广告组 ID。 |
##| ad_id | string | 广告 ID。 |
##| keyword_relevance_status | string | 关键词相关性分析的结果。<br><br>枚举值：<ul><li>`TO_BE_CALCULATED`：待计算。</li><li>`PARTIALLY_RELEVANT`：部分相关。</li><li>`RELEVANT`：相关。</li><li>`IRRELEVANT`：不相关。</li></ul> |
##| relevant_keyword_count | number | 相关的搜索关键词的数量。 |
##| relevant_keywords | string[] | 相关的搜索关键词列表。 |
##| irrelevant_keyword_count | number | 不相关的搜索关键词的数量。 |
##| irrelevant_keywords | string[] | 不相关的搜索关键词列表。 |
#| bid_budget | object | 出价和预算诊断的详情。 |
##| bid_budget_status | string | 出价和预算分析的结果。<br><br>枚举值：<ul><li>`GOOD`：良好。</li><li>`LOW_BID_AND_BUDGET`：出价和预算过低。</li><li>`LOW_BUDGET`：预算较低。</li><li>`LOW_BID`：出价较低。</li><li>`NO_DATA`：暂无数据。</li></ul> |
##| bid_suggestion_status | string | 针对出价的诊断结果。<br><br>枚举值：<ul><li>`GOOD`：良好。</li><li>`LOW`：出价较低。</li><li>`NO_DATA`：暂无数据。</li></ul> |
##| suggested_value | string | 建议出价。<br>根据历史数据，将出价至少增加到此建议值，广告组或广告可能会获得更多转化。 |
示例
获取现有广告组的诊断
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"bid_budget": {
"bid_budget_status": "GOOD",
"bid_suggestion_status": "GOOD"
},
"keyword_relevance": [
{
"ad_id": "{{ad_id}}",
"adgroup_id": "{{adgroup_id}}",
"irrelevant_keyword_count": 0,
"keyword_relevance_status": "RELEVANT",
"relevant_keyword_count": 1,
"relevant_keywords": [
"{{relevant_keyword}}"
]
}
],
"search_health_status": "NEED_IMPROVEMENT",
"search_volume": {
"diagnosis_result": "LOW",
"total_monthly_searches": 52689
},
"total_keyword_count": 1,
"total_relevant_keyword_count": 1
}
}
(/code)
获取现有广告的诊断
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"bid_budget": {
"bid_budget_status": "LOW_BUDGET",
"bid_suggestion_status": "GOOD"
},
"keyword_relevance": [
{
"ad_id": "{{ad_id}}",
"adgroup_id": "{{adgroup_id}}",
"irrelevant_keyword_count": 0,
"keyword_relevance_status": "RELEVANT",
"relevant_keyword_count": 2,
"relevant_keywords": [
"drink",
"food"
]
},
{
"ad_id": "{{ad_id}}",
"adgroup_id": "{{adgroup_id}}",
"irrelevant_keyword_count": 0,
"keyword_relevance_status": "RELEVANT",
"relevant_keyword_count": 2,
"relevant_keywords": [
"drink",
"food"
]
}
],
"search_health_status": "NEED_IMPROVEMENT",
"search_volume": {
"diagnosis_result": "HIGH",
"total_monthly_searches": 52472817
},
"total_keyword_count": 2,
"total_relevant_keyword_count": 4
}
}
(/code)