Miaozhen API Introduction

Miaozhen's Admonitor has been upgraded from Version 4.7 to Version 5.0 .It's able to process campaigns in PC and Mobile end in one single system which achieved cross platform data processing. Along with the upgrade of AdMonitor, its API has also upgraded. The details are as following: Note: The new API is compatible with the API Request using the old API.

Upgraded API	Upgrade Content	Description
campaigns/create	added a new parameter platform	The default value of platform is pc. When assigned pc, the campaign would be created in AdMonitor 4.7 and support the calculation of campaigns in PC end only；When assigned pm, that is PC and Mobile, the campaign would be created in AdMonitor 5.0, and support the calculation of campaigns in both pc and mobile platform.
	added a new parameter frequency_limit	The value of frequency_limit determines the maximum reach frequency of a certain campaign. The default value is 20, meaning calculate the Reach UV 1+ ~ 20+
	added a new parameter agency_id	When creating campaigns, use this parameter to indicate which agency it is.
campaigns/update	added a new parameter agency_id	help to update campaign's agency
campaigns/create_spot_with_plan	it's a new api	supports the creation of spot and spotplan at the same time
panels/list	added a new parameter platform	use this parameter to get the panel for pc or pm platform
agencies/show	Available	use this api to query a single agency
agencies/list	Available	use this api to query the list of all agencies
reports/basic/show	added a new parameter platform	Campaigns in the Admonitor 5.0 has three platform's data:PM(PC+Mobile)、PC、Mobile, set platform to one of this would show the corresponding platform's data.
reports/realtime/show
reports/reach/show

API Protocols

API Request

You access a Miaozhen API by sending a HTTP request to the API’s endpoint. Unless otherwise stated, the URL is HTTPS protocol starting with Miaozhen API domain: https://api.cn.miaozhen.com

APIs to retrieve data from require a GET request with parameters in the query string of the URL. APIs that create, update, or delete data require a POST with parameters in the HTTP body. The parameters should be application/x-www-form-urlencoded, charset UTF-8.

To access non-public data, you MUST use the parameter access_token granted from Miaozhen OAuth2 Service. See Miaozhen API Authentication.

There are some frequently-used parameters listed here.

• Common Parameters

  Name	Format	Example	Description
  access_token	TOKEN	1.2YotnFZFEjr1zCsi	Token from Miaozhen OAuth2 Service
  callback	FUNC	myfunc	Wrap JSON response in a callback method FUNC for JSONP. For example, appending callback=myfunc to a request will result in a response body of: myfunc(...). Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.
  suppress_response_codes	1	1	If this parameter is present, all responses will be returned with a 200 OK status code - even errors. This parameter exists to accommodate Flash and JavaScript applications running in browsers that intercept all non-200 responses.
  limit	M, N	0,2	Return at most N items from offset M. The offset of the initial item is 0 (not 1).
  order_asc	NAME	campaign_id	Return items in ascending order sorted by the values of attribute NAME of the items.
  order_desc	NAME	campaign_id	Return items in descending order sorted by the values of attribute NAME of the items.

  • order_asc an order_desc must not be in the same request.

• Example Request

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

API Response

The successful HTTP response should be an HTTP 200 (OK) status code with a plain text body presenting a JSON object, character set UTF-8.

• Example

   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"
  }
  

In case of client-side error or server-side error, the response will be an HTTP 400 (Bad Request) or 500 (Internal Server Error) status code respectively (200 if suppress_response_codes used). The response body will be a JSON error object, including the parameter error briefing the error, optionally error_description and error_code in some APIs.

• Example

  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
  }
  

---

Miaozhen APIs

CMS APIs

CMS is the product to manage Miaozhen’s meta ad data such as campaigns, panels and regions. For example, providing campaign id, you can query campaign name and campaign spot list from CMS APIs.

• Campaigns

  Status	Endpoint	Description
  ON	GET /cms/v1/campaigns/show	Show a campaign meta info.
  ON	GET /cms/v1/campaigns/show_spot	Show a campaign spot meta info.
  ON	GET /cms/v1/campaigns/list	List all campaigns you can access under some search conditions.
  ON	GET /cms/v1/campaigns/list_targets	List all targets of one campaign.
  ON	GET /cms/v1/campaigns/list_publishers	List all publishers of one campaign.
  ON	GET /cms/v1/campaigns/list_spots	List all spots of one campaign.
  ON	POST /cms/v1/campaigns/create	Create a new campaign.
  ON	POST /cms/v1/campaigns/create_spot	Create a new spot in a campaign.
  ON	POST /cms/v1/campaigns/publish_target	Create&publish a new target in a campaign.
  ON	POST /cms/v1/campaigns/delete	Delete a campaign.
  ON	POST /cms/v1/campaigns/delete_spot	Delete a spot in a campaign.
  ON	POST /cms/v1/campaigns/update	Update campaign info.
  ON	POST /cms/v1/campaigns/update_spot	Update spot info.
  OFF	POST /cms/v1/campaigns/update_spot_plan	Update spot plan.

• Minisites

  Status	Endpoint	Description
  ON	GET /cms/v1/minisites/show	Show a minisite meta info.
  ON	GET /cms/v1/minisites/list_events	List all events of one minisite.

• Regions

  Status	Endpoint	Description
  ON	GET /cms/v1/regions/show	Show a region meta info.
  ON	GET /cms/v1/regions/list	List all regions under some search conditions.

• Panels

  Status	Endpoint	Description
  ON	GET /cms/v1/panels/show	Show a panel meta info.
  ON	GET /cms/v1/panels/list	List all panels you can access under some search conditions.

• Advertisers

  Status	Endpoint	Description
  ON	GET /cms/v1/advertisers/show	Show an advertiser meta info.
  ON	GET /cms/v1/advertisers/list	List all advertisers under some search conditions.

• Agencies

  Status	Endpoint	Description
  ON	GET /cms/v1/agencies/show	Show an agency meta info.
  ON	GET /cms/v1/agencies/list	List all agencies under some search conditions.

AdMonitor APIs

AdMonitor is the product to track ad campaigns. For example, providing campaign id, you can query campaign tracking tags and reports from AdMonitor APIs.

• Tracking Tags

  Status	Endpoint	Description
  OFF	GET /admonitor/v1/tags/campaigns/show	Show tracking tags of a campaign.
  OFF	GET /admonitor/v1/tags/minisites/show	Show tracking tags of a minisite.

• Reports

  Status	Endpoint	Description
  ON	GET /admonitor/v1/reports/basic/show	Show a basic campaign report.
  OFF	GET /admonitor/v1/reports/basic/show_minisite	Show a basic minisite report.
  ON	GET /admonitor/v1/reports/realtime/show	Show a realtime campaign report.
  OFF	GET /admonitor/v1/reports/realtime/show_minisite	Show a realtime minisite report.
  ON	GET /admonitor/v1/reports/reach/show	Show a reach frequency report.
  OFF	GET /admonitor/v1/reports/audience/show_overview	Show an audience overview report.
  OFF	GET /admonitor/v1/reports/audience/show	Show an audience report.