搜索推广API

    KeywordService

    数据类型

    KeywordType

    属性名类型说明限制
    keywordIdLong关键词id -
    adgroupId Long推广单元id -
    campaignIdLong推广计划id -
    keywordString关键词字面长度限制:最大40个字节,
    1个中文按2个字节计算
    pricedouble 关键词竞价价格取值范围:(0,999.99] &&<= 所属计划预算
    pcDestinationUrlStringpc目标url 域名需和账户网站
    URL域名相同;
    长度限制:最大1024字节
    mobileDestinationUrlString移动访问URL域名需和账户网站
    URL域名相同;
    长度限制:最大1017个字节
    matchTypeInteger匹配模式取值范围:
    1 – 精确匹配;
    2 – 高级短语匹配;
    3 – 广泛匹配
    pauseboolean 暂停/启用关键词取值范围:
    true - 暂停;
    false - 启用
    statusInteger关键词状态取值范围:
    40-有效-移动url审核中;
    41-有效;
    42-暂停推广;
    43-不宜推广;
    44-搜索无效;
    45-待激活;
    46-审核中;
    47-搜索量过低;
    48-部分无效;
    49-计算机搜索无效;
    50-移动搜索无效。
    系统指定,客户端不可改变。
    说明:
    部分无效:投放设备为全部设备时,移动物料审核未过,
    计算机物料审核通过时,显示的是“部分无效”;
    搜索无效:将关键词的“搜索无效”状态进行设备的区分,
    当计算机出价低于计算机最低展现价格,
    则显示“计算机搜索无效”,当移动出价低于移动最低展现价格,
    则显示“移动搜索无效”;都无效时,显示搜索无效
    phraseTypeInteger高级短语细分匹配模式仅matchType=2的时候该字段生效;
    1.同义包含。
    2.精确包含。
    3.核心包含
    wmatchpreferInteger是否接受单元的分匹配出价比例0.启动。1.关闭
    pcQualityLongPC上该关键词的10分质量度0-10
    pcReliableIntegerPC上新广告维度下是否为临时质量度0临时,1正常
    pcReasonInteger质量度原因质量度0分原因:
    1相关性差
    2品牌保护
    3推广风险;
    质量度0分原因:
    1该品牌已被保护,建议关注品牌资质。
    2未进行加V认证,建议改善。
    3未进行年审,建议改善。
    4该类关键词推广风险高,建议更换。
    质量度1分原因:物料质量待提升,可参考细分维度诊断。
    质量度2-10分原因:具备一定的竞争力,可持续优化
    pcScaleInteger[]PC竞争关系分布,一个数组[],数组内有10个数值,
    分别代和自己有竞争关系的所有广告比例
    在[1,10]数值的推广数;[10,20,5,5,10,10,10,510,20];
    假设当前请求的wordid 字面鲜花,返回的竞争环境数组数据如上;
    其含义为:与当前请求的关键词有竞争关系的所有的关键词中,
    质量度分值为1分的关键词占比
    10%,2分20%,。。。。。。10分20%
    mobileQualityLong无线上该关键词的10分质量度0-10
    mobileReliableInteger无线上新广告维度下是否为临时质量度0临时,1正常
    mobileReasonInteger质量度原因质量度0分原因:
    1该品牌已被保护,建议关注品牌资质。
    2未进行加V认证,建议改善。
    3未进行年审,建议改善。
    4该类关键词推广风险高,建议更换。
    质量度1分原因:物料质量待提升,可参考细分维度诊断。
    质量度2-10分原因:具备一定的竞争力,可持续优化
    mobileScaleInteger[]无线上竞争关系分布,一个数组[],
    数组内有10个数值,分别代表在无线投放环境中
    和自己有竞争关系的所有广告的质量度分值分布
    类似pc竞争环境,但是pc和无线的竞争环境相互独立
    tabsInteger[]关键词物料标签数组取值范围:0~5(0表示无标签);
    目前仅支持一个物料标签,即取数组第一个元素作为物料标签
    leftPriceGuideString左侧指导价取值范围:(0,999.99]
    说明:当历史数据不足时会返回-
    left3PriceGuideString左侧前三指导价取值范围:(0,999.99]
    说明:当历史数据不足时会返回-
    mPriceGuideString移动指导价取值范围:(0,999.99]
    说明:当历史数据不足时会返回-

    接口描述

    getWord

    根据指定的单元id、关键词id获取关键词信息。

    Json示例

    {
    "ids":[***,***,…],"idType":11,"getTemp":0,"wordFields":["keywordId","keyword","adgroupId",…]
    }

    输入信息(getWordRequest)

    属性名类型说明限制
    wordFieldsString[] 指定需要返回的关键词属性请参考表KeywordFields
    idsLong[] 查询id集合:
    idType=5;类型为单元id,不超过50个;
    idType=11,类型为关键词id,不超过10000个
    必填,建议分批多次请求
    idTypeInteger5:单元id;
    11:关键词id
    必填
    getTemp Integer是否查询关键词影子选填,默认为0;
    0:只查询关键词本身;
    1:只查询关键词影子。
    想要获得关键词的全集,需要调用该方法两次,
    分别为getTemp=0和getTemp=1

    说明: 影子是指用户先向系统提交了关键词A,然后又对A进行修改(例如修改url),修改后的关键词为A’,在A'通过审核生效之前,线上的生效关键词仍然为A。此时getTemp为0查询到的是A,getTemp为1查询到的是A’。

    关键词字段(KeywordFields)

    本字段是每次必返的字段(不论用户传不传);复合字段是由多个简单属性组合的属性,用户请求会将这些简单字段打包返回;其余字段为简单字段,用户请求则返回。

    字段名说明字段类型
    keywordId关键词id基本字段
    campaignId推广计划id基本字段
    adgroupId推广单元id基本字段
    keyword关键词字面基本字段
    price关键词竞价价格基本字段
    pause暂停/启用关键词-
    matchType匹配模式-
    phraseType高级短语细分匹配模式-
    status关键词状态基本字段
    wmatchprefer是否接受匹配模式出价所确定的匹配模式-
    pcDestinationUrlpc目标url-
    pcQualityPC质量度复合字段,包括KeywordType中的如下属性:
    pcQuality,
    pcReliable,
    pcReason
    pcScalePC竞争关系数据-
    mobileDestinationUrl移动目标url-
    mobileQualitymobile质量度复合字段,包括KeywordType中的如下属性:
    mobileQuality,
    mobileReliable,
    mobileReason
    mobileScalemobile竞争关系数据-
    tabs物料标签选填

    返回信息(getWordResponse)

    属性名类型说明
    keywordTypesKeywordType[]不请求的的属性(基础属性除外)无返回值

    代码示例

    • 请求

    按照关键词id获取关键词的所有字段信息: 若只需获取部分字段,只需填入需要获取的字段值;若需按单元id获取,请设置idType=5。

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "ids": [
      keyword_id
        ],
        "getTemp": 0,
        "idType": 11,
        "wordFields": [
            "campaignId",
            "adgroupId",
            "keywordId",
            "pcDestinationUrl",
            "mobileDestinationUrl",
            "phraseType",
            "keyword",
            "price",
            "matchType",
            "pause",
            "status",
            "wmatchprefer",
            "pcQuality",
            "pcScale",
            "mobileQuality",
            "mobileScale"
        ]
      }
    }
    • 返回 返回关键词的全部信息:

      { "header": { "desc": "success", "failures": [], "oprs": 1, "succ": 1, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "campaignId": campaign_id, "keywordId": keyword_id, "adgroupId": adgroup_id, "keyword": "keyword", "price": 5, "matchType": 1, "pause": false, "status": 46, "pcDestinationUrl": "http://www.your_website.com", "mobileDestinationUrl": "http://www.your_website.com", "phraseType": 1, "wmatchprefer": 1, "owmatch": 1, "pcQuality": 1, "pcReliable": 1, "pcReason": 1, "pcScale": [ -1, -1, -1, -1, -1, -1, -1, -1, -1, -1 ], "mobileQuality": 1, "mobileReliable": 1, "mobileReason": 1, "mobileScale": [ -1, -1, -1, -1, -1, -1, -1, -1, -1, -1 ] } ] } }

    addWord

    新增关键词(可批量)。

    Json示例

    {
        "keywordTypes":[{"adgroupId":***,"keyword":***,…},{"adgroupId":***,"keyword":"***","price":***,"pause":***,"matchType":***,…},…]
    }

    输入参数(addWordRequest)

    属性名类型说明限制
    keywordTypes KeywordType[] 新增关键词对象数组,参见下表:单次请求不超过10000;建议分批多次请求

    新增KeywordType[]时,限制如下:

    属性名类型说明限制
    keywordId Long 关键词id 无效
    campaignIdLong 推广计划id 无效
    adgroupId Long推广单元id 必填
    keyword String关键词字面必填
    pricedouble 关键词竞价价格选填;默认值为该关键词所属单元出价
    pcDestinationUrlString目标url1、device=0(即全部设备),该属性为选填,默认值为NULL,
    检索时会使用关联创意的pcDestinationUrl;
    2、若所属计划device=1(即仅移动),
    该属性为无效属性
    mobileDestinationUrlString移动访问URL该属性为选填,默认值为NULL,
    检索时会使用关联创意的mobileDestinationUrl
    matchTypeInteger匹配模式选填;默认值为3
    pauseboolean 暂停/启用关键词选填;默认值为false
    statusInt关键词状态无效属性
    phraseTypeInteger高级短语细分匹配模式选填;默认为1;
    仅matchType=2的时候生效;
    1同义包含。
    2精确包含。
    3核心包含
    wmatchpreferInteger是否接受单元的分匹配出价比例选填;默认为1。0启动,1关闭
    pcQualityLongPC 10分质量度无效
    pcReliableIntegerPC上新广告维度下是否为临时质量度无效
    pcReasonInteger质量度原因无效
    pcScaleInteger[]PC竞争关系分布无效
    mobileQualityLong无线10分质量度无效
    mobileReliableInteger无线上新广告维度下是否为临时质量度无效
    mobileReasonInteger质量度原因无效
    mobileScaleInteger[]无线上竞争关系分布无效
    tabsInteger[]物料标签(选填)
    取值范围:0~5(0表示没有添加标签)
    如果填入[],则表示没有添加标签,等同于标签为0
    目前仅支持一个物料标签,即取数组第一个元素作为物料标签

    返回信息(addWordResponse)

    属性名类型说明限制
    keywordTypes KeywordType[] 新增关键词对象数组按请求顺序返回添加成功的关键词,
    添加失败的关键词返回错误信息及位置

    代码示例

    • 请求

    在某个单元下添加一个关键词:

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "keywordTypes": [
            {
                "keyword": "keyword",
                "adgroupId": your_adgroup_id,
                "matchType": 2,
                "price": 5.0,
                "pause": false,
                "pcDestinationUrl": "www.your_website.com/***",
                "mobileDestinationUrl": "www.your_website.com/***",
                "phraseType": 3,
                "wmatchPrefer": 1
            }
        ]
      }
    }
    • 返回 返回用户添加的信息:

      { "header": { "desc": "success", "failures": [], "oprs": 1, "succ": 1, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ { "keywordId": new_keyword_id, "adgroupId": your_adgroup_id, "keyword": "keyword", "price": 5, "matchType": 2, "pause": false, "pcDestinationUrl": "http://www.your_website.com", "mobileDestinationUrl": "http://www.your_website.com", "phraseType": 3 } ] } }

    updateWord

    更新关键词(可批量)。

    Json示例

    {
        "keywordTypes":[{"keywordId":***,"price":***,…},{"keywordId":***,"matchType":"***","price":***,"pause":***,"matchType":***,"pcDestinationUrl":"***",,…},…]
    }

    输入参数(updateWordRequest)

    属性名类型说明限制
    keywordTypes KeywordType[] 新增关键词对象数组参见下表;单次请求不超过10000;建议分批多次请求。

    更新KeywordType[]的限制如下:

    属性名类型说明限制
    keywordId Long关键词id 必填
    campaignId Long推广计划id 无效
    adgroupId Long推广单元id 无效
    keyword String关键词字面无效
    pricedouble 关键词竞价价格选填;默认值为NULL:不更新该属性;0:取消该关键词出价,此时采用所属单元出价
    pcDestinationUrlString目标url 1、若所属计划device=0(即设备属性设置为“全部设备”),
    该属性为选填,
    默认值为NULL:不更新该属性;
    “”(空串):取消url设置;
    2、若所属计划device=1(即设备属性设置为仅移动设备),
    该属性为无效属性
    mobileDestinationUrlString移动访问URL该属性为选填,
    默认值为NULL:不更新该属性;
    “”(空串):取消url设置
    matchTypeInteger匹配模式选填;默认值为NULL:不更新该属性
    pauseboolean 暂停/启用关键词选填;默认值为NULL:不更新该属性
    statusInteger关键词状态无效属性
    phraseTypeInteger高级短语细分匹配模式选填;
    默认值为NULL:不更新该属性;
    仅matchType=2的时候生效;
    1.同义包含。
    2.精确包含。
    3.核心包含
    wmatchpreferInteger是否接受单元的分匹配出价比例选填;默认为1。0启动,1关闭
    pcQualityLongPC 10分质量度无效字段
    pcReliableIntegerPC上新广告维度下是否为临时质量度无效字段
    pcReasonInteger质量度原因无效字段
    pcScaleInteger[]PC竞争关系分布无效字段
    mobileQualityLong无线10分质量度无效字段
    mobileReliableInteger无线上新广告维度下是否为临时质量度无效字段
    mobileReasonInteger质量度原因无效字段
    mobileScaleInteger[]无线上竞争关系分布无效字段
    tabsInteger[]物料标签(选填);
    更新取值范围:0~5 (0表示清空标签);空数组[]表示清空标签,等同于标签id=0;
    说明:如果客户打了多个标签,选第一个标签
    默认值为NULL:不更新该属性

    返回信息(updateWordResponse)

    属性名类型说明限制
    keywordTypes KeywordType[] 更新关键词对象数组按输入顺序返回成功的KeywordType[]数组,
    更新失败的关键词对象不返回。

    代码示例

    • 请求

    更新某个关键词:

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "keywordTypes": [
            {
                "keyword": "new_keyword",
                "keywordId": your_keyword_id,
                "matchType": 2,
                "price": 2.0,
                "pause": false,
                "pcDestinationUrl": "www.your_website.com/***",
                "mobileDestinationUrl": "www.your_website.com/***",
                "phraseType": 1,
                "wmatchPrefer": 1
            }
        ]
      }
    }
    • 返回

    只返回用户更新的字段信息:

    {
        "header": {
            "desc": "success",
            "failures": [],
            "oprs": 1,
            "succ": 1,
            "oprtime": 0,
            "quota": used_quota_of_this_operation,
            "rquota": your_remain_quota,
            "status": 0
        },
        "body": {
            "data": [
                {
                    "keywordId": your_keyword_id,
                    "adgroupId": your_adgroup_id,
                    "keyword": "new_keyword",
                    "price": 2,
                    "matchType": 2,
                    "pause": false,
                    "pcDestinationUrl": "http://www.your_website.com",
                    "mobileDestinationUrl": "http://www.your_website.com",
                    "phraseType": 1
                }
            ]
        }
    }

    deleteWord

    删除指定的关键词(可批量)

    Json示例

    {
        "keywordIds":[***,***,***,…]
    }

    输入信息(deleteWordRequest)

    属性名类型说明限制
    keywordIds Long[] - 单次请求不超过10000;建议分批多次请求

    返回信息(deleteWordResponse)

    属性名类型说明限制
    -删除失败的id查看错误提示Total返回删除成功的数量。

    代码示例

    • 请求

    删除两个关键词:

    {
    "header":{
    	"opUsername":"searchlab",   			//mcc操作员账户名称
        "opPassword":"*********"        		//mcc操作员账户密码
        "tgUsername":"searchlab", 
        "tgPassword":"*********", 
        "tgSubname":"searchlab",				//mcc被操作的账户
        "bceUser":"014df051fa131234a2a*****" 	//mcc类型的bceuser
    },
    "body":{
        "keywordIds": [
    		keyword_id_1,
    		keyword_id_2
        ]
    }
    }
    • 返回

      { "header": { "desc": "success", "failures": [], "oprs": 2, "succ": 2, "oprtime": 0, "quota": used_quota_of_this_operation, "rquota": your_remain_quota, "status": 0 }, "body": { "data": [ ] } }

    一篇
    LiveReportService
    一篇
    ToolKitService