Campaign Forecast Requests

Note:

Campaign forecasts do not yield meaningful results if you have eCPM enabled on your account, because it is not possible to enter a price in the forecast. As a result the simulated campaign has zero as a price and only ever gets picked in the simulation forecast when none of the other campaigns with a price takes the spot. This skewed result will not match reality, when you were to enter and run the campaign in the system. See Campaign Settings for information on enabling and disabling eCPM.

Request Body Format

To create campaign forecasts, you need to supply a body to the request with the following format:
Note: All parameters are optional unless explicitly stated.
{
    "campaign": {
        "advertiser": "<string>",
        "agency": "<string>",
        "brand": "<string>",
        "name": "<string>",
        "customId": "<string>",
        "frontload": "<0|10|20|30|40|50|60|70|80|90|100>",
        "priority": "<integer>",    (Number between 1 and 10)
        "targeting": {
            "targetingTemplates": "<string>",     (ID of the targeting template)
            "targetingRules": {
                "locationRules": [LocationRuleBean],
                "tagAndPartnerRules": [TagRuleBean or ContentPartnerRuleBean],
                "categoryRules": [CategoryRuleBean],
                "frequencyRules": [FrequencyRuleBean],
                "audienceRules": {"<audience data provider id>": AudienceSegmentRuleBean}
            },
            "parentOverrides": {
                "contentRules": "<boolean>",
                "tagAndPartnerRules": "<boolean>",
                "frequencyRules": "<boolean>",
                "locationRules": "<boolean>",
                "audienceRules": "<boolean>"
            }
        },
        "goals": [    (One goal is required)
               {     
            "customId": "<string>",
            "name": "<string>",    (Required)
            "startDate": "<string>",    (Required)
            "endDate": "<string>",      (Required, unless deliveryGoal type is RTB)
            "priority": "<integer>",    (Number between 1 and 10),
            "frontload": "<0|10|20|30|40|50|60|70|80|90|100>",
            "targeting": {
                "targetingTemplates": "<string>",     (ID of the targeting template),
                "targetingRules": {     (See note below for more information)
                    "locationRules": [LocationRuleBean],
                    "tagAndPartnerRules": [TagRuleBean or ContentPartnerRuleBean],
                    "categoryRules": [CategoryRuleBean],
                    "frequencyRules": [FrequencyRuleBean],
                    "audienceRules": {"<audience data provider id>": AudienceSegmentRuleBean}
                },
                "parentOverrides": {
                    "contentRules": "<boolean>",
                    "tagAndPartnerRules": "<boolean>",
                    "frequencyRules": "<boolean>",
                    "locationRules": "<boolean>",
                    "audienceRules": "<boolean>"
                }
            },
            "variant": "<NORMAL|BUMPER>",    (Required, refers to goal mode; "BUMPER" corresponds to sponsor goal mode in the Pulse UI)
            "positionRestriction": "<ANY|FIRST|LAST|FIRST_OR_LAST|BREAK_EXCLUSIVE>",
            "deliveryGoal": {    (Required)
                "value": "<number>",
                "type": "<IMPRESSION|COMPLETE|FIRST_QUARTILE|SECOND_QUARTILE|THIRD_QUARTILE|RTB>"
            },
            "ads": [    (One ad is required)
                {    
                "name": "<string>",    (Required)
                "customId": "<string>",
                "format": "<string>",    (Required, see below for more info)
                "deviceContainers": [    (Required; valid device container UUID, you can target multiple device containers.)
                    "<string>",
                    "<string>"
                ]
                "startDate": "<string>",
                "endDate": "<string>"
              }
            ],
            "sequence": "<integer>",
            "dailyCap": "<integer>",     (Must be non-negative integer)
            "marketplaceId": "<string>"  (A market place ID may be entered when deliveryGoal type is IMPRESSION or RTB)
        }
      ]
    }
}

, where:

  • Targeting rules are limited to location, tag or content, category, frequency and audience targeting. Setting the IpRuleBean, UserAgentRuleBean and TimeRuleBean is currently not supported when creating campaign forecasts. For more information on setting the targeting rules, the available parameters and their values, please refer to Update Targeting Template Rules.
  • startDate and endDate must be either in the format <yyyy-MM-dd>T<hh:mm:ss.sss>Z, or in epoch time in milliseconds. Whatever format you select, the timestamp is always interpreted according to the UTC timezone. It is preferable that startDate and endDate are entered to the whole hour, meaning to leave minutes and seconds as zero. For example: 2018-08-20T15:00:00Z.
  • The startDate must be at least one day in the future.
  • The endDate must be strictly larger than the startDate and may not be more than 100 days in the future, counting from today's date. It is recommended that endDate is at least one full day after startDate to get a meaningful forecast.
    Note: In case the deliveryGoal's type is RTB, then the endDate may be left blank (you must still provide the field in the body), because most real-time bid campaigns do not have an end date. If left blank, then the endDate is automatically set to 100 days from today's date.
  • Possible ad format values are:
    • preroll_standard, midroll_standard, postroll_standard
    • preroll_interactive, midroll_interactive, postroll_interactive
    • preroll_selector, midroll_selector, postroll_selector
    • preroll_takeover, midroll_takeover, postroll_takeover
    • preroll_iptv, midroll_iptv, postroll_iptv
    • pause_ad, overlay_site, inskin

Create a Campaign Forecast Job

Method POST
URL https://api.videoplaza.com/api/2.0/forecast/campaign
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body Request Body Format
Success response

HTTP status: 202 Accepted

Header: Location: URI to the location of the campaign forecast job

Body: -

Example:

Request header:

POST /api/2.0/forecast/campaign HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body:

{
    "campaign": {
        "name": "Campaign Test",
        "priority": 5,
        "targeting": {
            "targetingTemplates": [
                "053a4218-87c1-491d-83ac-6136abf0a866"
            ],
            "targetingRules": {
                "locationRules": [
                    {
                        "locationId": "752",
                        "locationType": "COUNTRY",
                        "locationName": "sweden",
                        "access": "ALLOW"
                    }
                ],
                "tagAndPartnerRules": [
                    {
                        "resourceType": "TAG",
                        "ruleType": "NONE_OF",
                        "tag": "violence"
                    }
                ],
                "categoryRules": [
                    {
                        "categoryId": "df5480fd-ca38-43c8-a44c-4240965e2023",
                        "categoryName": "Sport",
                        "ruleType": "AT_LEAST_ONE_OF"
                    }
                ],
                "frequencyRules": [
                    {
                        "impressions": 2,
                        "timeUnit": "DAY"
                    }
                ],
                "audienceRules": {
                    "7915b4ad-0572-4d88-bcf9-7f0813c953b3": [
                        {
                            "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[0]=1",
                            "segmentName": "Gender:Male",
                            "ruleType": "ALL_OF"
                        },
                        {
                            "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[1]=3",
                            "segmentName": "Age:21-29",
                            "ruleType": "ALL_OF"
                        }
                    ]
                }
            },
            "parentOverrides": {
                "contentRules": true,
                "tagAndPartnerRules": true,
                "frequencyRules": true,
                "locationRules": true,
                "audienceRules": true
            }
        },
        "goals": [
            {
                "name": "Test Goal",
                "startDate": 1498687200000,
                "endDate": 1499896799000,
                "variant": "NORMAL",
                "positionRestriction": "ANY",
                "deliveryGoal": {
                    "value": 100000,
                    "type": "IMPRESSION"
                },
                "ads": [
                    {
                        "name": "Ad 1",
                        "format": "preroll_standard",
                        "deviceContainers": [
                            "6b79564c-8a8c-102f-9f01-001e4f3cd645",
                            "86d28d24-d025-4633-a081-bea93de04dc3",
                            "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
                        ]
                    },
                    {
                        "name": "Ad 2",
                        "format": "midroll_standard",
                        "deviceContainers": [
                            "6b79564c-8a8c-102f-9f01-001e4f3cd645",
                            "86d28d24-d025-4633-a081-bea93de04dc3",
                            "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
                        ]
                    }
                ]
            }
        ]
    }
}

Success response:

HTTP status:
    202 (Accepted)

Header:
  Location: <URI with the location of the campaign forecast job>

Check Campaign Forecast Job Status

Method GET
URL https://api.videoplaza.com/api/2.0/forecast/job/{jobId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the campaign forecast job
Query params -
Body -
Success response

HTTP status: 201 Created

Header: Location: URI to the location of the campaign forecast report

Body: -

Note:

Possible HTTP status responses and their meaning:

  • 200 (OK): job has status QUEUED, PREPARING_SIMULATION, PROCESSING or FAILED.
  • 201 (Created): job completed. The location header contains the location of the finished forecast report.
  • 404 (Not Found): no job with the given ID found.

Example:

Request header:

GET /api/2.0/forecast/job/bc0e1f07-c04f-4060-9c33-4ffc0d8d0390 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
        201 (Created)  
Header:
  Location: <URI with the location of your campaign forecast report>

Cancel Campaign Forecast Job

Method POST
URL https://api.videoplaza.com/api/2.0/forecast/job/{jobId}/cancel
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the campaign forecast job
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: -

Example:

Request header:

POST /api/2.0/forecast/job/bc0e1f07-c04f-4060-9c33-4ffc0d8d0390/cancel HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
    200 (OK)

Get a Finished Campaign Forecast Report

Method GET
URL https://api.videoplaza.com/api/2.0/forecast/report/campaign/{id}
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the campaign forecast report
Query params exclude-competing-goals: set to true to exclude any competing goals from the campaign forecast report. By default, competing goals are included in the campaign forecast report.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: FeasibilityForecastResultBean

Example:

Request header:

GET /api/2.0/forecast/report/campaign/bc0e1f07-c04f-4060-9c33-4ffc0d8d0390 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
    200 (OK)   

Body:
{
    "campaign": {
        "advertiser": null,
        "agency": null,
        "brand": null,
        "name": "Campaign Test",
        "customId": null,
        "frontload": null,
        "priority": 5,
        "targeting": {
            "targetingTemplates": [
                "053a4218-87c1-491d-83ac-6136abf0a866"
            ],
            "targetingRules": {
                "locationRules": [
                    {
                        "locationId": "752",
                        "locationType": "COUNTRY",
                        "locationName": "sweden",
                        "access": "ALLOW"
                    }
                ],
                "tagAndPartnerRules": [
                    {
                        "resourceType": "TAG",
                        "ruleType": "NONE_OF",
                        "tag": "violence"
                    }
                ],
                "categoryRules": [
                    {
                        "categoryId": "df5480fd-ca38-43c8-a44c-4240965e2023",
                        "categoryName": "Sport",
                        "ruleType": "AT_LEAST_ONE_OF"
                    }
                ],
                "ipRules": [],
                "userAgentRules": [],
                "timeRules": [],
                "frequencyRules": [
                    {
                        "impressions": 2,
                        "timeUnit": "DAY"
                    }
                ],
                "audienceRules": {
                    "7915b4ad-0572-4d88-bcf9-7f0813c953b3": [
                        {
                            "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[0]=1",
                            "segmentName": "Gender:Male",
                            "ruleType": "ALL_OF"
                        },
                        {
                            "segmentId": "7915b4ad-0572-4d88-bcf9-7f0813c953b3[1]=3",
                            "segmentName": "Age:21-29",
                            "ruleType": "ALL_OF"
                        }
                    ]
                }
            },
            "parentOverrides": {
                "contentRules": true,
                "tagAndPartnerRules": true,
                "frequencyRules": true,
                "locationRules": true,
                "audienceRules": true
            }
        },
        "goals": [
            {
                "customId": null,
                "name": "Test Goal",
                "startDate": 1498687200000,
                "endDate": 1499896799000,
                "priority": null,
                "frontload": null,
                "targeting": null,
                "variant": "NORMAL",
                "positionRestriction": "ANY",
                "deliveryGoal": {
                    "value": 100000,
                    "type": "IMPRESSION"
                },
                "ads": [
                    {
                        "name": "Ad 1",
                        "customId": null,
                        "format": "preroll_standard",
                        "deviceContainers": [
                            "6b79564c-8a8c-102f-9f01-001e4f3cd645",
                            "86d28d24-d025-4633-a081-bea93de04dc3",
                            "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
                        ],
                        "startDate": null,
                        "endDate": null
                    },
                    {
                        "name": "Ad 2",
                        "customId": null,
                        "format": "midroll_standard",
                        "deviceContainers": [
                            "6b79564c-8a8c-102f-9f01-001e4f3cd645",
                            "86d28d24-d025-4633-a081-bea93de04dc3",
                            "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
                        ],
                        "startDate": null,
                        "endDate": null
                    }
                ],
                "sequence": null,
                "dailyCap": null,
                "marketplaceID": ""
            }
        ]
    },
    "forecasts": {
        "Test Goal": {
            "deliveryGoal": {
                "value": 100000,
                "type": "IMPRESSION"
            },
            "customId": null,
            "name": "Campaign Test",
            "forecastedDelivery": 0,
            "accessibleInventory": 0,
            "deliveryMargin": 0
        }
    },
    "unusedInventory": 0,
    "unusedInventoryByDay": {
        "2017-07-09T22:00:00.000+0000": 0,
        "2017-06-29T22:00:00.000+0000": 0,
        "2017-07-04T22:00:00.000+0000": 0,
        "2017-07-03T22:00:00.000+0000": 0,
        "2017-07-08T22:00:00.000+0000": 0,
        "2017-06-28T22:00:00.000+0000": 0,
        "2017-07-02T22:00:00.000+0000": 0,
        "2017-07-07T22:00:00.000+0000": 0,
        "2017-07-01T22:00:00.000+0000": 0,
        "2017-07-06T22:00:00.000+0000": 0,
        "2017-07-11T22:00:00.000+0000": 0,
        "2017-06-30T22:00:00.000+0000": 0,
        "2017-07-05T22:00:00.000+0000": 0,
        "2017-07-10T22:00:00.000+0000": 0
    },
    "maximumDelivery": 0,
    "maximumDeliveryByDay": {
        "2017-07-09T22:00:00.000+0000": 0,
        "2017-06-29T22:00:00.000+0000": 0,
        "2017-07-04T22:00:00.000+0000": 0,
        "2017-07-03T22:00:00.000+0000": 0,
        "2017-07-08T22:00:00.000+0000": 0,
        "2017-06-28T22:00:00.000+0000": 0,
        "2017-07-02T22:00:00.000+0000": 0,
        "2017-07-07T22:00:00.000+0000": 0,
        "2017-07-01T22:00:00.000+0000": 0,
        "2017-07-06T22:00:00.000+0000": 0,
        "2017-07-11T22:00:00.000+0000": 0,
        "2017-06-30T22:00:00.000+0000": 0,
        "2017-07-05T22:00:00.000+0000": 0,
        "2017-07-10T22:00:00.000+0000": 0
    },
    "competingGoals": {
        "impactedBy": []
    },
    "name": "Campaign Test",
    "jobId": "bc0e1f07-c04f-4060-9c33-4ffc0d8d0390"
}

해당 내용이 도움 되었습니까?