Miaozhen CMS/Campaigns API v1

Campaign Management System (CMS) is the product to manage Miaozhen’s meta 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 - Get Data

Show Campaign

• Endpoint

  GET /cms/v1/campaigns/show
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  access_token	required

• Example Response

   {
      "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"],
      "linked_minisites": ["1","2"],
      "linked_iplib": "IPlib-Region-0000-top100-20120428105600"
  }
  

---

Show Campaign Spot

• Endpoint

  GET /cms/v1/campaigns/show_spot
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  spot_id_str	required	abc0	string representation of the spot
  keyword	optional	on
  access_token	required

• Example Response

      {
          "spot_id": "40",
          "spot_id_str": "e",
          "publisher_name": "test site",
          "channel_name": "news",
          "placement_name": "top banner",
          "keyword":[
            {
              "keyword_id": 4018469,
              "keyword_name": "白醋洗衣服"
            },
            {
              "keyword_id": 4018470,
              "keyword_name": "abctestword"
            },
            ...
          ]
          "GUID": "RTX123456",
          "CAGUID": "XDF234",
          "shopid": "234",
          "customize": "66666"
      }
  

---

List Campaigns

List all campaigns you can access with some search conditions.

• Endpoint

  GET /cms/v1/campaigns/list
  

• Parameters

  Name		Format	Example	Description
  campaign_id	optional	ID1,ID2,…	12,13,14	List campaigns, campaign_id must be within the ID list (comma separated).
  campaign_type	optional	TP1,TP2,…	admonitor	Search: campaign_type contains must be within the type list (comma separated).
  campaign_name	optional	PATTERN	food	Search: campaign_name contains PATTERN.
  advertiser_name	optional	PATTERN	yum	Search: advertiser_name contains PATTERN.
  agency_name	optional	PATTERN		Search: agency_name contains PATTERN.
  brand_name	optional	PATTERN	kfc	Search: brand_name contains PATTERN.
  creator_name	optional	PATTERN	lee	Search: creator_name contains PATTERN.
  status	optional	INT(1..3)	1	Search: campaign status is 1:not started, 2:ongoing, 3:ended.
  access_token	required
  limit	optional	M, N	0,2	Return the M'th item to the M+N'th item. Default 0,500. M:return items from item M, N:return N number of items.
  order_asc	optional	NAME	campaign_id	It can only be: campaign_id, campaign_name, advertiser_name, agency_name, brand_name, creator_name, status.
  order_desc	optional	NAME	campaign_id	See order_asc.

  • If more than one search condition parameters specified, only items that fulfill all conditions will be returned (AND logic).

• Example Response

  [
      {
          "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"],
          "linked_minisites": ["1","2"],
          "linked_iplib": "IPlib-Region-0000-top100-20120428105600"
      },
      ...
  ]
  

---

List Campaign Targets

• Endpoint

  GET /cms/v1/campaigns/list_targets
  

• Parameters

  Name		Format	Example	Description
  campaign_id	required	ID	12	List targets of the campaign ID
  panel_id	optional	ID1,ID2,…	china-123,test	Search: panel_id must be within the ID list (comma separated).
  target_id	optional	ID1,ID2,…	2,3	Search: target_id must be within the ID list (comma separated).
  access_token	required
  limit	optional	M, N	0,2	Return the M'th item to the M+N'th item. Default 0,500. M:return items from item M, N:return N number of items.
  order_asc	optional	NAME	panel_id	It can only be one of the follows: panel_id, target_id.
  order_desc	optional	NAME	panel_id	See order_asc.

  • If more than one search condition parameters specified, only items that fulfill all conditions will be returned (AND logic).

• Example Response

  [
      {
           target_id: "2",
           target_name: "F20-24Y",
           panel_id: "china-123"
      },
      {
           target_id: "3",
           target_name: "M20-24Y",
           panel_id: "china-123"
      },
      ...
  ]
  

---

List Campaign Publishers

• Endpoint

  GET /cms/v1/campaigns/list_publishers
  

• Parameters

  Name		Format	Example	Description
  campaign_id	required	ID	12	List publishers of the campaign ID
  publisher_id	optional	ID1,ID2,…	2,3,4	Search: publishers whose publisher_id within the ID list (comma separated).
  access_token	required
  limit	optional	M, N	0,2	Return the M'th item to the M+N'th item. Default 0,500. M:return items from item M, N:return N number of items.
  order_asc	optional	NAME	publisher_id	It can only be: publisher_id.
  order_desc	optional	NAME	publisher_id	See order_asc.

  • If more than one search condition parameters specified, only campaigns that fulfill all conditions will be returned (AND logic).

• Example Response

  [
      {
          publisher_id: "2",
          publisher_name: "Google"
      },
      {
          publisher_id: "3",
          publisher_name: "Twitter"
      },
      ...
  ]
  

---

List Campaign Spots

A spot is an ad placement within one campaign. The plan of a spot is a group of online time periods of the spot.

• Endpoint

  GET /cms/v1/campaigns/list_spots
  

• Parameters

  Name		Format	Example	Description
  campaign_id	required	ID	12	List publishers of the campaign ID
  publisher_id	optional	ID1,ID2,…	2,3,4	Search: spots whose publisher_id within the ID list (comma separated).
  spot_id	optional	ID1,ID2,…	40,41,42	Search: spots whose spot_id within the ID list (comma separated).
  show_plan	optional	INT(0..1)	1	Whether to show spots plan, 0 (default): not show, 1: show
  from_date	optional	YYYY-MM-DD	2013-01-01	Show spots plan from date YYYY-MM-DD, if not specified or not valid, from the beginning of the plan
  to_date	optional	YYYY-MM-DD	2013-01-07	Show spots plan to date YYYY-MM-DD, if not specified or not valid, to the end of the plan
  code_type	optional	NAME	http	Choose the type of monitoring code，http(default)：http code，https：https code
  access_token	required
  limit	optional	M, N	0,2	Return the M'th item to the M+N'th item. Default 0,500. M:return items from item M, N:return N number of items.
  order_asc	optional	NAME	publisher_id	It can only be one of the follows: spot_id, publisher_id.
  order_desc	optional	NAME	spot_id	See order_asc.

  • If more than one search condition parameters specified, only items that fulfill all conditions will be returned (AND logic).

• Example Response

  [
      {
          "spot_id": "40",
          "spot_id_str": "e",
          "publisher_id": "3",
          "channel_name": "news",
          "placement_name": "top banner",
          "GUID": "RTX123456",
          "CAGUID": "XDF234",
          "shopid": "234",
          "customize": "66666"
          "landing_page": "http://www.facebook.com",
          "tracking_tags":
          [
              "impression_url": "http://g.cn.miaozhen.com/x.gif?k=123&p=456&o=",
              "click_url": "http://e.cn.miaozhen.com/r.gif?k=123&p=456&o=http://www.facebook.com"
          ],
          "spot_plan":
          [
              {
                  "date": "2013-01-01",
                  "est_impression": 2000,
                  "est_click": 10,
                  "creative_id": "1"
               },
               ...
          ]
      },
      ...
  ]
  

---

Campaigns - Create Data

Create Campaign

• Endpoint

  POST /cms/v1/campaigns/create
  

• Parameters

  Name		Example	Description
  campaign_type	optional	admonitor	Default: admonitor
  platform	optional	pm	Must be one of the follows: pc(default), pm
  campaign_name	required	test	Cannot be empty. It’s suggested to use a unique name. AdMonitor may add some suffix to the name to make it unique in the system.
  calculation_type	optional	1.0	Must be one of the follows: 1.0(default), 2.0,2.1
  start_date	required	2012-12-20	YYYY-MM-DD, should be later than today.
  end_date	required	2013-01-05	YYYY-MM-DD, should be later than start_date.
  frequency_limit	optional	20	INT, Default 20. Range: 1-80
  advertiser_id	optional	1	The advertiser of the campaign. You can use List Advertisers to list all available advertiser ids.
  agency_id	optional	2	The agency of the campaign. You can use List Agencies to list all available agency ids.
  panel_id	optional	china-123	The panel linked to the campaign. You can use List Panels to list all available panel ids. It is strongly recommended to leave it default (the latest panel id).
  wares	optional	china-123
  industry	optional	china-123
  ad_campaign_type	optional	china-123
  slot_type	optional	china-123
  freq_capping	optional	china-123
  description	optional	CampaignDesc
  access_token	required

• Example Response

  • If succeeded, the new created campaing_id will be returned.

     {
        "campaign_id": "123"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_campaign_name",
        "error_description": "The 'campaign_name' should not be empty."
    }
    

---

Create Campaign Spot

• Endpoint

  POST /cms/v1/campaigns/create_spot
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  publisher_name	required	yahoo
  channel_name	required	news
  placement_name	required	123
  placement_type	optional	display	Must be one of the follows: display (default), video, search
  freq_capping	optional	S0+	Consists of FC mode (S or M), FC target (n+, n-) and FC period (D, W or M), FC mode and FC target are required item.
  tracking_timing	optional	0	The intended timing of sending tracking request, default: 0.
  pricing_model	optional	CPM	Should be CPM, CPD, CPC, compensation etc.
  unit_price	optional	1	Only integer supported. If pricing_model is CPD, unit_price is the price per day.
  referrer_url	optional	http://www.ads.com	The referrer page URL of the ad.
  landing_page	optional	http://www.wtf.com
  access_token	required

• Example Response

  • If succeeded, the new created spot_id will be returned.

     {
        "campaign_id": "123",
        "spot_id": "40",
        "spot_id_str": "e",
        "publisher_id": "1"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    {
        "error": "invalid_placement_name",
        "error_description": "The 'placement_name' should not be empty."
    }
    

---

Create & Publish Target

• Endpoint

  POST /cms/v1/campaigns/publish_target
  

• Parameters

  Name		Example	Description
  campaign_id	required	12
  target_name	required	F24~29Y	Cannot be empty. It’s suggested to use a unique name in one campaign.
  tag_id	required	34,56	The tags which are supposed to be chosen in the target.You can use List Panels to list all available tag ids.
  access_token	required

• Example Response

  • If succeeded, the new published target_id will be returned.

     {
        "target_id": "6",
        "target_name": "F20-24Y",
        "panel_id": "china-123"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    {
        "error": "is wrong.",
        "error_description": "The 'target_name' has been existed in this campaign."
    }
    

---

Create Campaign Spot With Plan

• Endpoint

  POST /cms/v1/campaigns/create_spot_with_plan
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  publisher_name	required	yahoo
  channel_name	required	news
  placement_name	required	123
  placement_type	optional	display	Must be one of the follows: display (default), video, search
  tracking_timing	optional	0	The intended timing of sending tracking request, default: 0.
  pricing_model	optional	CPM	Should be CPM, CPD, CPC, compensation etc.
  unit_price	optional	1	Only integer supported. If pricing_model is CPD, unit_price is the price per day.
  referrer_url	optional	http://www.ads.com	The referrer page URL of the ad.
  landing_page	optional	http://www.wtf.com
  slot_begin[]	optional	2013-11-11	Beginning of the time slot. YYYY-MM-DD
  slot_duration[]	optional	30	Duration (in days) of the time slot.
  est_impression[]	optional	100	Estimated total impressions during the time slot.
  est_click[]	optional	10000	Estimated total clicks during the time slot.
  access_token	required

• Example Response

  • If succeeded, the new created spot_id will be returned.

     {
        "campaign_id": "123",
        "spot_id": "40",
        "spot_id_str": "e",
        "publisher_id": "1"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_placement_name",
        "error_description": "The 'placement_name' should not be empty."
    }
    

---

Campaigns - Delete Data

Delete Campaign

• Endpoint

  POST /cms/v1/campaigns/delete
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  access_token	required

• Example Response

  • If succeeded, the deleted campaign_id will be returned.

     {
        "campaign_id": "123"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_campaign_id",
        "error_description": "The 'campaign_id' cannot be found."
    }
    

---

Delete Campaign Spot

• Endpoint

  POST /cms/v1/campaigns/delete_spot
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  spot_id	required	40
  access_token	required

• Example Response

  • If succeeded, the deleted spot_id will be returned.

     {
        "campaign_id": "123",
        "spot_id": "40",
        "spot_id_str": "e"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_spot_id",
        "error_description": "The 'spot_id' cannot be found."
    }
    

---

---

Campaigns - Update Data

Update Campaign

• Endpoint

  POST /cms/v1/campaigns/update
  

• Parameters

  Name		Example	Description
  campaign_id	required	1
  campaign_type	optional	admonitor	Default: admonitor
  campaign_name	optional	test
  start_date	optional	2012-12-20	YYYY-MM-DD, should be later than today.
  end_date	optional	2013-01-05	YYYY-MM-DD, should be later than start_date.
  advertiser_id	optional	1	The advertiser of the campaign. You can use List Advertisers to list all available advertiser ids.
  agency_id	optional	1	The agency of the campaign. You can use List_Agencies to list all available agency ids.
  panel_id	optional	china-123	The panel linked to the campaign. You can use List Panels to list all available panel ids.
  description	optional	CampaignDesc
  access_token	required

• Example Response

  • If succeeded, the updated campaign_id will be returned.

     {
        "campaign_id": "123"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_campaign_id",
        "error_description": "The 'campaign_id' cannot be found."
    }
    

---

Update Campaign Spot

• Endpoint

  POST /cms/v1/campaigns/update_spot
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  spot_id	required	3
  publisher_name	optional	3
  placement_name	optional	header
  channel_name	optional	news
  landing_page	optional	http://www.wtf.com
  access_token	required

• Example Response

  • If succeeded, the updated spot_id will be returned.

    {
        "campaign_id": "123",
        "spot_id": "40",
        "spot_id_str": "e"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_spot_id",
        "error_description": "The 'spot_id' cannot be found."
    }
    

---

Update Campaign Spot Plan

This API will update the whole spot plan of a spot with the parameters provided. Note that if you do not pass any time slot parameters, all the time slots of the spot will be deleted.

• Endpoint

  POST /cms/v1/campaigns/update_spot_plan
  

• Parameters

  Name		Example	Description
  campaign_id	required	123
  spot_id	required	40
  slot_begin[]	optional	2013-11-11	Beginning of the time slot. YYYY-MM-DD
  slot_duration[]	optional	30	Duration (in days) of the time slot.
  est_impression[]	optional	100	Estimated total impressions during the time slot.
  est_click[]	optional	10000	Estimated total clicks during the time slot.
  access_token	required

• Example Response

  • If succeeded, the updated spot_id will be returned.

    {
        "campaign_id": "123",
        "spot_id": "40",
        "spot_id_str": "e"
    }
    

  • If failed, error will be returned. See error response format for detail.

    HTTP/1.1 400 Bad Request
    Content-Type: application/json;charset=UTF-8
    
    {
        "error": "invalid_spot_id",
        "error_description": "The 'spot_id' cannot be found."
    }
    

---