Miaozhen API Introduction

API协议

API请求

通过向API接口发送HTTP请求来访问Miaozhen API。除非另有说明，URL是以Miaozhen API域名https://api.cn.miaozhen.com开头的HTTPS协议。

用于检索数据的API需要使用URL的查询字符串中的参数进行GET请求。创建、更新或删除数据的API需要HTTP中包含参数的POST请求。这些参数应该是application / x-www-form-urlencoded，字符集UTF-8。

获取token

要访问非公开数据，须使用Miaozhen OAuth2 Service授予的参数[access_token] 。

请求地址

POST /oauth/token

参数

名称必选示例描述
grant_type true password grant_type必须为password
username true john 用户名
password true 8888 密码
client_id true admapi API账号用户名
client_secret true 7Fjfp0ZBr1KtDRbn API账号密码

名称	必选	示例	描述
grant_type	true	password	grant_type必须为password
username	true	john	用户名
password	true	8888	密码
client_id	true	admapi	API账号用户名
client_secret	true	7Fjfp0ZBr1KtDRbn	API账号密码

响应实例


{
 "token_type": "bearer",
 "access_token": "2.DS9SMCcVMIJUYBoGMDAxNTc1IgxhZG1QbVRlc3RBcGkyAgIB.MCwCFB1MCZFS1bOnjRks-h-JZAiQ1Le7AhQ7ejI6-q4k2vIghzQ2oXDgWJys5w",
 "refresh_token": "93ec7138-c388-4131-9166-c7f2f8f092d6",
 "expires_in": 3600,
 "scope": "monitor op",
 "product_id_list": [
     2,
     1
 ],
 "uid": 0000,
 "uname": "john",
 "user_number": "1650172955"
}

注意：access_token在短时间内过期（默认情况下为1小时）。

如果您不知道client_id/client_secret或用户名/密码，请咨询秒针客户经理团队。

常用参数

名称格式示例描述
access_token TOKEN 1.2YotnFZFEjr1zCsi 用于验证登录的访问令牌串
callback FUNC myfunc 将JSON响应包装在JSONP的回调方法FUNC中。例如，附加callback=myfunc到请求, 将导致响应正文中出现：myfunc(...)。回调只能包含字母数字字符和下划线;任何无效字符都将被去除。
suppress_response_codes 1 1 如果此参数存在，所有响应将返回200 OK的状态代码---甚至是error。此参数的存在是为了适应运行在拦截所有非200响应的浏览器中的Flash和JavaScript应用程序。
limit M，N 0,2 从偏移量M中返回最多N个项目。初始项目的偏移量为0（不是1）。
order_asc NAME campaign_id 按照项目的属性NAME的值排序按升序返回项目。
order_desc NAME campaign_id 按照项目的属性NAME的值排序按降序返回项目；与order_asc不能在同一个请求中。

名称	格式	示例	描述
access_token	TOKEN	1.2YotnFZFEjr1zCsi	用于验证登录的访问令牌串
callback	FUNC	myfunc	将JSON响应包装在JSONP的回调方法FUNC中。例如，附加callback=myfunc到请求, 将导致响应正文中出现：myfunc(...)。回调只能包含字母数字字符和下划线;任何无效字符都将被去除。
suppress_response_codes	1	1	如果此参数存在，所有响应将返回200 OK的状态代码---甚至是error。此参数的存在是为了适应运行在拦截所有非200响应的浏览器中的Flash和JavaScript应用程序。
limit	M，N	0,2	从偏移量M中返回最多N个项目。初始项目的偏移量为0（不是1）。
order_asc	NAME	campaign_id	按照项目的属性NAME的值排序按升序返回项目。
order_desc	NAME	campaign_id	按照项目的属性NAME的值排序按降序返回项目；与order_asc不能在同一个请求中。

请求示例


xxxxxxxxxx
GET /admonitor/v1/campaigns/show?campaign_id=123&access_token=1.2YotnFZFEjr1zCsi HTTP/1.1
Host: api.cn.miaozhen.com

API响应

成功的HTTP响应为HTTP 200（OK）状态代码，其中显示JSON对象的纯文本正文，字符集UTF-8。

响应示例


xxxxxxxxxx
 HTTP/1.1 200 OK
 Content-Type: application/json;charset=UTF-8
 {
"campaign_id": "123",
"campaign_type": "admonitor",
"campaign_name": "test campaign 1",
"start_date": "2012-12-20",
"end_date": "2013-01-05",
"description": "This is a test campaign.",
"agency_name": "Test Agency",
"advertiser_name": "Test Advertiser",
"brand_name": "Test Brand",
"creator_name": "jetlee",
"linked_panels": ["china-123","test-2012l225"],
"linked_minisites": ["1","2"],
"linked_iplib": "IPlib-Region-0000-top100-20120428105600"
}

错误响应

在客户端错误或服务器端错误的情况下，响应将分别是HTTP 400（错误请求）或500（内部服务器错误）状态代码（如果使用suppress_response_codes，得到的是200）。响应正文将是一个JSON的错误对象，包括参数error来简要介绍错误，在API中可能出现error_description和error_code。

请求示例


xxxxxxxxxx
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"error": "token_required",
"error_description": "An access token is required to request this resource.",
"error_code": 123
}

秒针AdMonitor API

CMS APIs

CMS是管理秒针的元数据（如广告活动，panel和地域）的产品。可通过活动ID从CMS API查询广告活动名称和广告活动点位列表等。

广告活动

状态请求地址描述
ON GET /cms/v1/campaigns/show 显示广告活动信息。
ON GET /cms/v1/campaigns/show_spot 显示广告活动点位信息。
ON GET /cms/v1/campaigns/list 列出可以在某些搜索条件下访问的所有广告活动。
ON GET /cms/v1/campaigns/list_targets 列出一个广告活动的所有目标人群。
ON GET /cms/v1/campaigns/list_publishers 列出一个广告活动的所有媒体。
ON GET /cms/v1/campaigns/list_spots 列出一个活动的所有点位（含监测代码）。
ON POST /cms/v1/campaigns/create 创建新的广告活动。
ON POST /cms/v1/campaigns/create_spot 在广告活动中创建新的点位。
ON POST /cms/v1/campaigns/publish_target 在广告活动中创建并发布新的目标人群。
ON POST /cms/v1/campaigns/create_spot_with_plan 创建活动排期。
ON POST /cms/v1/campaigns/delete 删除广告活动。
ON POST /cms/v1/campaigns/delete_spot 删除广告活动中的某个点位。
ON POST /cms/v1/campaigns/update 更新广告活动信息。
ON POST /cms/v1/campaigns/update_spot 更新点位信息。

状态	请求地址	描述
ON	GET /cms/v1/campaigns/show	显示广告活动信息。
ON	GET /cms/v1/campaigns/show_spot	显示广告活动点位信息。
ON	GET /cms/v1/campaigns/list	列出可以在某些搜索条件下访问的所有广告活动。
ON	GET /cms/v1/campaigns/list_targets	列出一个广告活动的所有目标人群。
ON	GET /cms/v1/campaigns/list_publishers	列出一个广告活动的所有媒体。
ON	GET /cms/v1/campaigns/list_spots	列出一个活动的所有点位（含监测代码）。
ON	POST /cms/v1/campaigns/create	创建新的广告活动。
ON	POST /cms/v1/campaigns/create_spot	在广告活动中创建新的点位。
ON	POST /cms/v1/campaigns/publish_target	在广告活动中创建并发布新的目标人群。
ON	POST /cms/v1/campaigns/create_spot_with_plan	创建活动排期。
ON	POST /cms/v1/campaigns/delete	删除广告活动。
ON	POST /cms/v1/campaigns/delete_spot	删除广告活动中的某个点位。
ON	POST /cms/v1/campaigns/update	更新广告活动信息。
ON	POST /cms/v1/campaigns/update_spot	更新点位信息。

地域

状态请求地址描述
ON GET /cms/v1/regions/show 显示地域信息。
ON GET /cms/v1/regions/list 列出某些搜索条件下的所有地域。

状态	请求地址	描述
ON	GET /cms/v1/regions/show	显示地域信息。
ON	GET /cms/v1/regions/list	列出某些搜索条件下的所有地域。

Panels

状态请求地址描述
ON GET /cms/v1/panels/show 显示panel信息。
ON GET /cms/v1/panels/list 列出某些搜索条件下访问的所有panel。

状态	请求地址	描述
ON	GET /cms/v1/panels/show	显示panel信息。
ON	GET /cms/v1/panels/list	列出某些搜索条件下访问的所有panel。

广告主

状态请求地址描述
ON GET /cms/v1/advertisers/show 显示广告主的信息。
ON GET /cms/v1/advertisers/list 列出某些搜索条件下的所有广告主。

状态	请求地址	描述
ON	GET /cms/v1/advertisers/show	显示广告主的信息。
ON	GET /cms/v1/advertisers/list	列出某些搜索条件下的所有广告主。

品牌

状态请求地址描述
ON GET /cms/v1/brands/show 显示品牌的信息。
ON GET /cms/v1/brands/list 列出某广告主ID下的所有品牌信息。

状态	请求地址	描述
ON	GET /cms/v1/brands/show	显示品牌的信息。
ON	GET /cms/v1/brands/list	列出某广告主ID下的所有品牌信息。

代理商

状态请求地址描述
ON GET /cms/v1/agencies/show 显示代理商信息。
ON GET /cms/v1/agencies/list 列出某些搜索条件下的所有代理商。

状态	请求地址	描述
ON	GET /cms/v1/agencies/show	显示代理商信息。
ON	GET /cms/v1/agencies/list	列出某些搜索条件下的所有代理商。

商品信息

状态请求地址描述
ON GET /cms/v1/product/list 列出某些搜索条件下的所有商品。

状态	请求地址	描述
ON	GET /cms/v1/product/list	列出某些搜索条件下的所有商品。

剧目信息

状态请求地址描述
ON GET /cms/v1/programs/list 列出某些搜索条件下的所有剧目信息。

状态	请求地址	描述
ON	GET /cms/v1/programs/list	列出某些搜索条件下的所有剧目信息。

广告位类型

状态请求地址描述
ON GET /cms/v1/plmttype/list 列出某些搜索条件下的所有广告位类型。

状态	请求地址	描述
ON	GET /cms/v1/plmttype/list	列出某些搜索条件下的所有广告位类型。

AdMonitor APIs

AdMonitor是广告监测产品。例如，可以通过活动ID在AdMonitor API查询广告数据报告。

报告

状态请求地址描述
ON GET /admonitor/v1/reports/basic/show 显示广告活动基础数据。
ON GET /admonitor/v1/reports/realtime/show 显示广告活动实时数据。
ON GET /admonitor/v1/report/reach/show 显示到达人群报告。
ON GET /admonitor/v1/report/basic/progress 活动计算进度查询。

状态	请求地址	描述
ON	GET /admonitor/v1/reports/basic/show	显示广告活动基础数据。
ON	GET /admonitor/v1/reports/realtime/show	显示广告活动实时数据。
ON	GET /admonitor/v1/report/reach/show	显示到达人群报告。
ON	GET /admonitor/v1/report/basic/progress	活动计算进度查询。