Ad Forecaster API
Paths
/campaigns
GET List Campaigns
The Campaigns endpoint returns an array containing all of the existing campaigns.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | An array of campaigns. | Array of Campaign |
PUT Replace Campaigns
Replaces the existing campaigns with the ones received from this request.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
body | body | Array of Campaign | Required | The new array of campaigns. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Campaigns
Deletes all existing campaigns.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/campaigns/{id}
GET Get Campaign
Returns a campaign based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The campaign id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | The campaign. | Campaign |
400 | Error response, containing error message. | ErrorResponse |
POST Add Campaign
Adds a new existing campaign.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The campaign id. |
body | body | Campaign | Required | The new campaign. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
PUT Update Campaign
Updates an existing campaign.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The campaign id. |
body | body | Campaign | Required | The updated campaign. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Campaign
Deletes a campaign based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The campaign id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/frequency_groups
GET List Frequency Groups
The Frequency Groups endpoint returns an array containing all of the existing frequency groups.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | An array of frequency groups | Array of FrequencyGroup |
PUT Replace Frequency Groups
Replaces the existing frequency groups with the ones received from this request.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
body | body | Array of FrequencyGroup | Required | The new array of frequency groups. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Frequency Groups
Deletes the existing frequency groups.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/frequency_groups/{id}
GET Get Frequency Group
Returns a frequency group based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The frequency group id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | The frequency group. | FrequencyGroup |
400 | Error response, containing error message. | ErrorResponse |
POST Add Frequency Group
Adds a new existing frequency group.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The frequency group id. |
body | body | FrequencyGroup | Required | The new frequency group. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
PUT Update Frequency Group
Updates an existing frequency group.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The frequency group id. |
body | body | FrequencyGroup | Required | The updated frequency group. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Frequency Group
Deletes a frequency group based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The frequency group id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/hints
GET List Forecaster Hints
The Forecaster Hints endpoint returns an array containing all of the existing forecaster hints.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | An array of forecaster hints. | Array of ForecasterHint |
PUT Replace Forecaster Hints
Replaces the existing forecaster hints with the ones received from this request.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
body | body | Array of ForecasterHint | Required | The new array of forecaster hints. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Forecaster Hints
Deletes the existing forecaster hints.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/hints/{id}
GET Get Forecaster Hint
Returns a forecaster hint based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The forecaster hint id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | The forecaster hint. | ForecasterHint |
400 | Error response, containing error message. | ErrorResponse |
POST Add Forecaster Hint
Adds a new existing forecaster hint.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The forecaster hint id. |
body | body | ForecasterHint | Required | The new forecaster hint. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
PUT Update Forecaster Hint
Updates an existing forecaster hint.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The forecaster hint id. |
body | body | ForecasterHint | Required | The updated forecaster hint. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Forecaster Hint
Deletes a forecaster hint based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The forecaster hint id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/targeting
GET List Targeting Rules
The Targeting Rules endpoint returns an array containing all of the existing targeting rules.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | An array of targeting rules. | Array of ExistingTargetingRule |
PUT Replace Targeting Rules
Replaces the existing targeting rules with the ones received from this request.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
body | body | Array of ExistingTargetingRule | Required | The new array of targeting rules. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Targeting Rules
Deletes the existing targeting rules.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/targeting/{id}
GET Get Targeting Rule
Returns a targeting rule based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The targeting rule id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | The targeting rule. | ExistingTargetingRule |
400 | Error response, containing error message. | ErrorResponse |
POST Add Targeting Rule
Adds a new existing targeting rule.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The targeting rule id. |
body | body | ExistingTargetingRule | Required | The new targeting rule. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
PUT Update Targeting Rule
Updates an existing targeting rule.
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The targeting rule id. |
body | body | ExistingTargetingRule | Required | The updated targeting rule. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete Targeting Rule
Deletes a targeting rule based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The targeting rule id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/forecast
GET List All Running Forecasts
List all running synchronous and asyncronous forecasts with the request body.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
details | path | Boolean | Default: true | show detailed list of forecasts. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing JSON response object. | ForecasterStatus |
POST Create Forecast
Performs a deliverability forecast. Since the forecast processing might take some time to complete, it is possible to request an asynchronous forecast, where the server returns immediately with an automatically generated forecast id. This forecast id can then be used to query the server on the status of the running forecast (using the
/forecast/{id}
interface).
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
async | query | Boolean | Default: false | Request an asynchronous deliverability forecast. |
body | body | ForecastRequest | Required | The JSON object that describes the forecast request. |
Cache-Control | header | String | When set to |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response for synchronous forecast requests, the response contains the forecast JSON response object. | ForecastResult |
202 | Normal response for asynchronous forecast requests; the response contains the ID of the requested forecast. The Location header contains the URI that can be used to poll for that particular forecast request. | PartialForecastResult |
400 | Error response, containing error message. | ErrorResponse |
DELETE Delete all forecasts
Deletes all forecasts currently queued or running.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
force | query | Boolean | Default: false | If true, in addition to deleting queued forecasts, also cancels and removes running or finished forecasts. Otherwise, only queued forecasts are deleted. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
/forecast/{id}
GET Get Forecast Result
Gets results of previously requested asynchronous forecast.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The forecast id. |
Responses
Status Code | Description | Schema |
---|---|---|
202 | Normal response, containing JSON response object for a partial result. | PartialForecastResult |
200 | Normal response, containing JSON response object for a final result. | PartialForecastResult |
400 | Error response, containing error message. | ErrorResponse |
404 | Forecast ID not found. | ErrorResponse |
DELETE Cancels a Running Forecast
Cancels a running forecast based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The forecast id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
404 | Forecast ID not found. | ErrorResponse |
/forecast/available
POST Create Available Forecast
Performs an availability forecast for a given set of targeting criteria and priority, i.e. the available (and booked) predicted amount of impressions and unique users, taking into account the existing running campaigns. Since the forecast processing might take some time to complete, it is possible to request an asynchronous forecast, where the server returns immediately with an automatically generated forecast id. This forecast id can then be used to query the server on the status of the running forecast (using the
/forecast/available/{id}
interface).
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
async | query | Boolean | Default: false | Request an asynchronous available forecast. |
body | body | AvailableForecastRequest | Required | The JSON object that describes the available forecast request. |
Cache-Control | header | String | When set to |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response for synchronous available forecast requests, the response contains the available forecast JSON response object. | AvailableForecastResult |
202 | Normal response for asynchronous available forecast requests; the response contains the ID of the requested available forecast. The Location header contains the URI that can be used to poll for that particular available forecast request. | PartialAvailableForecastResult |
400 | Error response, containing error message. | ErrorResponse |
/forecast/available/{id}
GET Get Available Forecast Result
Gets results of previously requested asynchronous available forecast.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The available forecast id. |
Responses
Status Code | Description | Schema |
---|---|---|
202 | Normal response, containing JSON response object for a partial result. | PartialAvailableForecastResult |
200 | Normal response, containing JSON response object for a final result. | PartialAvailableForecastResult |
400 | Error response, containing error message. | ErrorResponse |
404 | Eligible forecast ID not found. | ErrorResponse |
DELETE Cancels a Running Available Forecast
Cancels a running available forecast based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The available forecast id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
404 | Available forecast ID not found. | ErrorResponse |
/forecast/eligible
POST Create Eligible Forecast
Performs a total eligibility forecast for a given set of targeting criteria, i.e. the total predicted amount of impressions and unique users disregarding any running campaigns. Since the forecast query processing might take some time to complete, it is possible to request an asynchronous forecast query, where the server returns immediately with an automatically generated forecast query id. This forecast query id can then be used to query the server on the status of the running forecast query (using the
/forecast/eligible/{id}
interface).
MIME
- Consumes
application/json
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
async | query | Boolean | Default: false | Request an asynchronous eligible forecast. |
body | body | EligibleForecastRequest | Required | The JSON object that describes the eligible forecast request. |
Cache-Control | header | String | When set to |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response for synchronous eligible forecast requests, the response contains the eligible forecast JSON response object. | EligibleForecastResult |
202 | Normal response for asynchronous eligible forecast requests; the response contains the ID of the requested eligible forecast. The Location header contains the URI that can be used to poll for that particular eligible forecast request. | PartialEligibleForecastResult |
400 | Error response, containing error message. | ErrorResponse |
/forecast/eligible/{id}
GET Get Eligible Forecast Result
Gets results of previously requested asynchronous eligible forecast.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The eligible forecast id. |
Responses
Status Code | Description | Schema |
---|---|---|
202 | Normal response, containing JSON response object for a partial result. | PartialEligibleForecastResult |
200 | Normal response, containing JSON response object for a final result. | PartialEligibleForecastResult |
400 | Error response, containing error message. | ErrorResponse |
404 | Eligible forecast ID not found. | ErrorResponse |
DELETE Cancels a Running Eligible Forecast
Cancels a running eligible forecast based on its ID.
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
id | path | String | Required | The eligible forecast id. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing success message. | MessageResponse |
400 | Error response, containing error message. | ErrorResponse |
404 | Eligible forecast ID not found. | ErrorResponse |
/forecast/existing_campaigns
GET Get Existing Campaigns Forecast Results
Gets the forecast results of the defined existing campaigns
MIME
- Produces
application/json
Parameters
Name | In | Type | Flags | Description |
---|---|---|---|---|
sampling | query | Integer | Default: 1 | The sampling. |
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing JSON response object. | ForecastResult |
400 | Error response, containing error message. | ErrorResponse |
/forecast/info
GET Get Forecaster System Info
Retrieves the current system info, e.g. start and end dates of available forecast data.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing JSON response object. | ForecasterInfo |
/forecast/fields
GET List Available Fields
Retrieve list of fields (Keys) which are allowed to be used for targeting rules in forecast requests and also which are allowed in the groupBy parameter.
MIME
- Produces
application/json
Responses
Status Code | Description | Schema |
---|---|---|
200 | Normal response, containing JSON response object. | FieldDescription |
Models
MessageResponse
Properties
Name | Type | Flags | Description |
---|---|---|---|
message | String | Required | System message. |
warnings | Array of Warning | Non-fatal warnings. |
ErrorResponse
Properties
Name | Type | Flags | Description |
---|---|---|---|
errorMessage | String | Required | Error message. |
FrequencyGroup
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | Unique identifier of the frequency group. |
campaignIds | Array of String | Required | IDs of the campaigns affected by the frequency group. |
frequencyCap | FrequencyCap | Required |
FrequencyCap
Properties
Name | Type | Flags | Description |
---|---|---|---|
nTimes | Integer | Required | The maximum number of times an ad is sown to a unique user. |
nMinutes | Integer | Default: 0 | The time window size, in minutes, to apply the frequency cap rule. Use 0 for no time limit. |
ForecastRequest
A request to perform a deliverability forecast for a set of new campaigns considering a set of planned campaings (including the campaigns stored via the
/campaigns
endpoint). It is also possible to override some of the values of the already existing campaigns (campaigns posted in the/campaigns
endpoint) for a particular forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
newCampaigns | Array of Campaign | Required | Array of campaign objects, representing the campaign(s) to be forecasted. If the field |
plannedCampaigns | Array of Campaign | Array of campaign objects, representing the planned campaign(s), forecast results will not be shown for these campaigns (can be an empty list). |
|
existingCampaignsOverrides | ExistingCampaignsOverridesMap | A map from campaign ids to fields to be overriden in the existing campaigns. |
|
frequencyGroups | FrequencyGroup | Array of frequency group objects to be applied in this forecast request. |
|
hints | Array of ForecasterHint | Array of forecaster hint objects to be applied in this forecast request. When defining hints in a forecast request the hint id is optional. If no id is provided an id like |
|
params | ForecastRequestParams | Parameter settings for the forecast request |
ForecastRequestParams
Properties
Name | Type | Flags | Description |
---|---|---|---|
sampling | Integer | Default: 1 | The level of sampling to use (between 0 and 3). 3 provides the quickest response and 0 for the highest accuracy. By default this is set to 1. |
responsiveness | Integer | Default: 1 | The responsiveness level to use (between 0 and 3). 3 provides the quickest response at the expense of less intermediate results and 0 results in more intermediate results but at the expense of performance. By default this is set to 1. |
groupBy | Array of String | Break the forecast results down by the given groupBy keys. Some caution should be used when choosing the groupBy keys, as some keys may have thousands of possible values and can produce very large responses. |
|
filterGroupBy | GroupedFilteringRule | Filter the forecast results breakdown by the given rule. An extra key, “groupedFiltered”, is added containing all the combined results that were filtered out by the rule. |
|
aggStats | Array of String | Aggregate the forecast stats down by the given aggStats keys. |
|
timeZone | String | Default: UTC | The time zone to use when grouping results with a time-related key (e.g. |
countLostOpportunities | Boolean | Default: false | Keep track of lost ad opportunities to other campaigns. For each forecasted campaign two additional values are returned with the results: lostImpressions and lostUniqueUsers. By default this flag is set to false. |
bookedByCampaign | Boolean | Default: false | On availability forecasts, keep track of booked impressions by existing campaign. |
rtbStats | Boolean | Default: false | Keep track of statistics of RTB data, such as the clearing price distribution and the ratio of impressions with price info. By default this flag is set to false. |
notifyUrl | String | The URL where an HTTP POST message (Notification) will be sent after an async forecast has finished. |
AvailableForecastRequest
A request to perform an availability forecast, i.e. querying the predicted inventory to find the total amount of available (and booked) impressions and unique users, taking into account any running campaigns and delivery logic.
Properties
Name | Type | Flags | Description |
---|---|---|---|
startDate | String (date-time) | Default: lowest available | Start date of the available forecast, as yyyy-mm-dd HH:MM:SS. |
endDate | String (date-time) | Default: highest available | End date of the available forecast, as yyyy-mm-dd HH:MM:SS. |
timeZone | String | Default: UTC | The time zone of the available forecast’s start and end dates (available time
zones). Additionally, targeting rules are evaluated in the available forecast’s time
zone, i.e. if the request timezone is set to “EST” a rule like |
frequencyCaps | Array of FrequencyCap | Array of frequency capping rules set for the availability forecast. |
|
targeting | Array of TargetingRuleContainer | The specified targeting for the available forecast. |
|
hints | Array of ForecasterHint | Array of forecaster hint objects to be applied in this forecast request. When defining hints in a forecast request the hint id is optional. If no id is provided an id like |
|
priority | Integer | The priority level at which availability will be calculated, impressions for existing campaigns with a “lower” priority than this will be considered available (as defined by the delivery logic algorithm, i.e. whether higher numeric values represent higher priority or lower). |
|
useMasterUserId | Boolean | Default: false | Whether to use a master user id (e.g. cross-device id) for unique user tracking and frequency capping. |
params | ForecastRequestParams | Parameter settings for the forecast request. Availability forecast requests accept an
extra parameter |
EligibleForecastRequest
A request to perform an eligible forecast, i.e. querying the predicted inventory to find the total amount of available impressions and unique users (without taking into account any running campaigns or delivery logic).
Properties
Name | Type | Flags | Description |
---|---|---|---|
startDate | String (date-time) | Default: lowest available | Start date of the eligible forecast, as yyyy-mm-dd HH:MM:SS. |
endDate | String (date-time) | Default: highest available | End date of the eligible forecast, as yyyy-mm-dd HH:MM:SS. |
timeZone | String | Default: UTC | The time zone of the eligible forecast’s start and end dates (available time zones).
Additionally, targeting rules are evaluated in the eligible forecast’s time zone, i.e. if the request timezone is set to “EST” a rule like |
frequencyCaps | Array of FrequencyCap | Array of frequency capping rules set for the eligibility forecast. |
|
targeting | Array of TargetingRuleContainer | The specified targeting for the eligible forecast. |
|
hints | Array of ForecasterHint | Array of forecaster hint objects to be applied in this forecast request. When defining hints in a forecast request the hint id is optional. If no id is provided an id like |
|
useMasterUserId | Boolean | Default: false | Whether to use a master user id (e.g. cross-device id) for unique user tracking and frequency capping. |
params | ForecastRequestParams | Parameter settings for the forecast request. The option |
ForecasterInfo
Properties
Name | Type | Flags | Description |
---|---|---|---|
startDate | String (local-date) | Required | The start date of the forecasted log data, as yyyy-mm-dd. |
endDate | String (local-date) | Required | The end date of the forecasted log data, as yyyy-mm-dd. |
pastStartDate | String (local-date) | The start date of the past (real) log data, as yyyy-mm-dd. |
|
pastEndDate | String (local-date) | The end date of the past (real) log data, as yyyy-mm-dd. |
|
shardCount | Integer | Required | The number of shards used. |
lastUpdate | String (date-time) | Required | The date-time when the system was updated, as yyyy-mm-dd HH:MM:SS. |
ForecasterStatus
Properties
Name | Type | Flags | Description |
---|---|---|---|
queued | Integer | Required | The number of queued forecasts. |
executing | Integer | Required | The number of executing forecasts. |
details | Array of ForecastStatus | The detailed list of active forecasts. |
ForecastStatus
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | The forecast id. |
type | String | Required | The type of forecast (sync of async). |
status | String | Required | The current status of the forecast (queued, started, partial, finished). |
progress | Number | Required | The progress of the running forecast. |
eta | String | The expected time of accomplishment of the forecast, a datetime in the ISO 8601 format with timezone information. It is only available if the forecast is asynchronous and there are partial results available (i.e. the progress is between 0% and 100%, exclusively). |
|
desc | String | The description of the current forecaster status. |
|
request | ForecastRequest | Required | The request associated with the forecast. |
ForecastResult
Properties
Name | Type | Flags | Description |
---|---|---|---|
total | CampaignForecasts | Required | Map of CampaignForecast, one key per campaign forecasted, containing total aggregated forecast results. |
grouped | Array of GroupedCampaignForecast | Array of GroupedCampaignForecast, one by each possible key for the groupBy parameter specified in the request. |
|
groupedFiltered | CampaignForecasts | Aggregated simplified CampaignForecasts that were filtered out by the filterGroupBy rule. |
|
percentiles | PercentileResult | PercentileData for each aggregated field. |
|
warnings | Array of Warning | List of non-fatal warnings. |
PartialForecastResult
A partial forecast result from an asynchronous forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | The forecast Id. |
status | String | Required | The current status of the forecast (can be one of: none, partial, finished). |
progress | Number | Required | The current progress of the forecast, in the range [0.0, 100.0]. |
eta | String | The expected time of accomplishment of the forecast, a datetime in the ISO 8601 format with timezone information. It is only available if the forecast is asynchronous and there are partial results available (i.e. the progress is between 0% and 100%, exclusively). |
|
desc | String | An informal description of the status of the forecast. |
|
resultStatus | String | The result status (can be one of: success, failure). |
|
result | ForecastResult | The current forecast result (for the given forecast progress). |
|
resultError | String | An error description if something went wrong during the forecast. |
AvailableForecastResult
An available forecast result.
Properties
Name | Type | Flags | Description |
---|---|---|---|
total | AvailableForecastValues | Required | An object containing the total aggregated available forecast results. |
grouped | Array of GroupedAvailableForecastValues | Array of GroupedAvailableForecastValues, one by each possible key for the groupBy parameter specified in the request. |
|
groupedFiltered | AvailableForecastValues | Aggregated simplified available forecast results that were filtered out by the filterGroupBy rule. |
|
warnings | Array of Warning | List of non-fatal warnings. |
PartialAvailableForecastResult
A partial available forecast result from an asynchronous available forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | The available forecast Id. |
status | String | Required | The current status of the available forecast (can be one of: none, partial, finished). |
progress | Number | Required | The current progress of the available forecast, in the range [0.0, 100.0]. |
eta | String | The expected time of accomplishment of the forecast, a datetime in the ISO 8601 format with timezone information. It is only available if the forecast is asynchronous and there are partial results available (i.e. the progress is between 0% and 100%, exclusively). |
|
desc | String | An informal description of the status of the available forecast. |
|
resultStatus | String | The result status (can be one of: success, failure). |
|
result | AvailableForecastResult | The current available forecast result (for the given progress). |
|
resultError | String | An error description if something went wrong during the available forecast. |
EligibleForecastResult
A eligible forecast result.
Properties
Name | Type | Flags | Description |
---|---|---|---|
total | EligibleForecastValues | Required | An object containing the total aggregated eligible forecast results. |
grouped | Array of GroupedEligibleForecastValues | Array of GroupedEligibleForecastValues, one by each possible key for the groupBy parameter specified in the request. |
|
groupedFiltered | EligibleForecastValues | Aggregated simplified eligible forecast results that were filtered out by the filterGroupBy rule. |
|
percentiles | PercentileResult | PercentileData for each aggregated field. |
|
warnings | Array of Warning | List of non-fatal warnings. |
PartialEligibleForecastResult
A partial eligible forecast result from an asynchronous eligible forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | The eligible forecast Id. |
status | String | Required | The current status of the eligible forecast (can be one of: none, partial, finished). |
progress | Number | Required | The current progress of the eligible forecast, in the range [0.0, 100.0]. |
eta | String | The expected time of accomplishment of the forecast, a datetime in the ISO 8601 format with timezone information. It is only available if the forecast is asynchronous and there are partial results available (i.e. the progress is between 0% and 100%, exclusively). |
|
desc | String | An informal description of the status of the eligible forecast. |
|
resultStatus | String | The result status (can be one of: success, failure). |
|
result | EligibleForecastResult | The current eligible forecast result (for the given progress). |
|
resultError | String | An error description if something went wrong during the eligible forecast. |
Campaign
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | Unique identifier of the campaign. |
startDate | String (date-time) | Required | Start date of the campaign, as yyyy-mm-dd HH:MM:SS. |
endDate | String (date-time) | Required | End date of the campaign, as yyyy-mm-dd HH:MM:SS. |
timeZone | String | Default: UTC | The time zone of the campaign’s start and end dates (available time zones).
Additionally, targeting rules are evaluated in the campaign’s time zone, i.e. if the campaign is set to “EST” a rule like |
priority | Integer | Required | Relative campaign priority, as used by the ad decision logic. Larger numbers correspond to higher priorities. |
deliverySchedule | DeliverySchedule | Default: asap | The delivery schedule for this campaign. For more information, check the Delivery Logic documentation. |
weight | Number | Default: 100.0 | Relative campaign weight, as used by the ad decision logic. |
impressions | Integer | The impression goal defined for the campaign (for the whole lifetime of the campaign). |
|
deliveredImpressions | Integer | Number of impressions delivered for the given campaign at the time of the last update. |
|
dailyCap | Integer | Maximum number of impressions to be delivered per day. |
|
frequencyCaps | Array of FrequencyCap | Array of frequency capping rules set for the campaign. |
|
targeting | Array of TargetingRuleContainer | The specified targeting for the campaign. |
|
retargeting | Array of String | IDs of the campaigns that this campaign is retargeting. |
|
useMasterUserId | Boolean | Default: false | Whether to use a master user id (e.g. cross-device id) for unique user tracking and frequency capping. |
lastUpdate | String (date-time) | The time of the last update of this campaign’s definition, as a valid ISO8601 string (e.g. 2016-01-11T17:31:10+00:00).
It defines the date for which the current state of the campaign (i.e. |
DeliverySchedule
A pacing strategy for a campaign.
Properties
Name | Type | Flags | Description |
---|---|---|---|
type | String with possible values:
|
Required Discriminator | The type of delivery schedule. |
AsapDeliverySchedule
extends DeliveryScheduleA delivery schedule that attempts to deliver all impressions as soon as possible.
EvenDeliverySchedule
extends DeliveryScheduleA delivery schedule that attempts to deliver impressions evenly during the campaign lifetime.
FrontloadedDeliverySchedule
extends DeliveryScheduleA delivery schedule that attempts to deliver impressions evenly with a bias during the campaign lifetime. For more information, check the Delivery Logic documentation.
ForecasterHint
A manual adjustment to the forecast results. Can either be a MultiplierHint or an ImpressionCountHint.
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | Unique identifier of the forecaster hint. |
type | String with possible values:
|
Required Discriminator | The type of forecaster hint. |
startDate | String (date-time) | Required | Start date, as yyyy-mm-dd HH:MM:SS. |
endDate | String (date-time) | Required | End date, as yyyy-mm-dd HH:MM:SS. |
timeZone | String | Default: UTC | The time zone of the hint’s start and end dates (available time zones).
Additionally, the rule is evaluated in the hints’s time zone, i.e. if the hint is set to “EST” a rule like |
rule | TargetingRule | Rule used to filter impressions. The hint will only be applied to impressions who conform to this rule. |
MultiplierHint
extends ForecasterHintA forecaster hint that multiplies the targeted traffic by a constant ammount. If this hint is active during a forecast, a
MODHNT
warning will be triggered.If the
inventoryPoolRule
parameter is set, the new traffic will be generated based on data targeted by this rule. Note that, if this parameter is set and the logs already contain impressions targeted by therule
field, those impressions will be ignored and aIPLHNT
waning will be triggered.For example, a multiplier of 2.0 with a
"rule":"site = \"NEW_SITE\""
and a"inventoryPoolRule":"site = \"OLD_SITE\""
will generate a new site with twice the traffic of “OLD_SITE”, but with the same characteristics. If a site named “NEW_SITE” already existed, its impressions would be overriden.
Properties
Name | Type | Flags | Description |
---|---|---|---|
multiplier | Number | Required | How many times to multiply traffic in the range. |
inventoryPoolRule | TargetingRule | If defined, this hint will create impressions based on this rule, modified to match the hint’s targeting rule (e.g. create English users with the same behaviour as French users). |
ImpressionCountHint
extends ForecasterHintA forecaster hint that sets the number of targeted impressions to a constant ammount. If this hint is active during a forecast, a
MODHNT
warning will be triggered.If there is not enough traffic to train this hint, it will create synthetic impressions according to the
rule
field, that might have blank fields. If this happens, aCRTHNT
warning will be triggered. Note that this will only work if theinventoryPoolRule
parameter is set or if therule
field contains enough information to create synthetic fields (i.e. all non-optional fields must appear in the rule).If the
inventoryPoolRule
parameter is set, the new traffic will be generated based on data targeted by this rule. Note that, if this parameter is set and the logs already contain impressions targeted by therule
field, those impressions will be ignored and aIPLHNT
waning will be triggered.For example, a impressionCount of 5000 with a
"rule":"site = \"NEW_SITE\""
and a"inventoryPoolRule":"site = \"OLD_SITE\""
will generate a new site with 5000 impressions based on the ones from “OLD_SITE”, but with the same characteristics. If a site named “NEW_SITE” already existed, its impressions would be overridden.
Properties
Name | Type | Flags | Description |
---|---|---|---|
impressionCount | Number | Required | Number of impressions to use on impressionCount hints. |
inventoryPoolRule | TargetingRule | If defined, this hint will create impressions based on this rule, modified to match the hint’s targeting rule (e.g. create English users with the same behaviour as French users). |
AverageResult
A set of averages of the fields defined in
aggStats
and the clearing CPM.
Properties
Name | Type | Flags | Description |
---|---|---|---|
clearingCpm | Number | The average of the clearing CPM for the campaign. |
Additional Properties ?
Type | Description |
---|---|
Number | The average of a field for the campaign. |
CampaignForecasts
Additional Properties ?
Type | Description |
---|---|
CampaignForecastValues | The map of campaign ids to results. |
CampaignForecastValues
The results of a forecast for a campaign.
Properties
Name | Type | Flags | Description |
---|---|---|---|
impressions | Integer | Required | Number of available ad impressions forecasted for the campaign. |
uniqueUsers | Integer | Number of unique users forecasted to be reached by the campaign. |
|
lostImpressions | Integer | Number of ad impressions matching campaign targeting criteria but unavailable for the campaign due to other overlapping campaigns. |
|
lostUniqueUsers | Integer | Number of unique users matching campaign targeting criteria but unavailable for the campaign due to other overlapping campaigns. |
|
avg | AverageResult | The average values of the aggregated fields for the campaign. |
|
peakRtbQueriesPerSecond | Integer | The maximum number of RTB queries in a second, for the forecasted campaign. |
GroupedCampaignForecast
The results of a grouped forecast for a campaign.
Properties
Name | Type | Flags | Description |
---|---|---|---|
key | GroupByKeys | Required | The combination of key values for the CampaignForecasts specified in the values attribute. |
values | CampaignForecasts | Required | The values for each campaign forecasted, grouped by the keys specified in the key attribute. |
AvailableForecastValues
The results of an available forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
available | AvailableForecastValue | Required | Results for predicted available inventory. |
booked | AvailableForecastBookedValue | Required | Results for predicted booked inventory. |
AvailableForecastValue
The result of an available forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
impressions | Integer | Required | Number of ad impressions in the predicted inventory. |
uniqueUsers | Integer | Number of unique users in the predicted inventory. |
AvailableForecastBookedValue
The result of an available forecast for booked inventory.
Properties
Name | Type | Flags | Description |
---|---|---|---|
impressions | Integer | Required | Number of ad impressions in the predicted booked inventory. |
uniqueUsers | Integer | Number of unique users in the predicted booked inventory. |
|
byCampaign | AvailableForecastCampaignValue | Results for predicted booked inventory grouped by existing campaign (if |
AvailableForecastCampaignValue
Additional Properties ?
Type | Description |
---|---|
AvailableForecastValue | The map of campaign ids to results. |
GroupedAvailableForecastValues
The results of a grouped available forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
key | GroupByKeys | Required | The combination of key values for the AvailableForecastValues specified in the value attribute. |
values | AvailableForecastValues | Required | The result of an available forecast, grouped by the keys specified in the key attribute. |
EligibleForecastValues
The results of a eligible forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
impressions | Integer | Required | Number of available ad impressions in the predicted inventory. |
uniqueUsers | Integer | Number of unique users in the predicted inventory. |
|
avg | AverageResult | The average values of the aggregated fields. |
|
peakRtbQueriesPerSecond | Integer | The maximum number of RTB queries in a second. |
GroupedEligibleForecastValues
The results of a grouped eligible forecast.
Properties
Name | Type | Flags | Description |
---|---|---|---|
key | GroupByKeys | Required | The combination of key values for the EligibleForecastValues specified in the value attribute. |
value | EligibleForecastValues | Required | The result of an eligible forecast, grouped by the keys specified in the key attribute. |
GroupByKeys
The values for each of the keys in a
groupBy
operation.
Additional Properties ?
Type | Description |
---|---|
String | A mapping from a field name to one of its values. |
PercentileResult
A set of results for each field given in
aggStats
and the clearing CPM (ifrtbStats
is true) grouped by percentile. There’s one entry in this object for each campaign, with the campaign id (the object will have a single “eligible” campaign for eligible forecasts).
Properties
Name | Type | Flags | Description |
---|---|---|---|
clearingCpm | CampaignPercentileResult | The percentiles for the clearing CPM for the campaigns. |
Additional Properties ?
Type | Description |
---|---|
CampaignPercentileResult | The percentiles for the campaigns for each of the fields given in |
CampaignPercentileResult
The percentile results for each campaign.
Additional Properties ?
Type | Description |
---|---|
Array of PercentileData | The percentiles for each campaign. |
PercentileData
Relevant information about a percentile.
Properties
Name | Type | Flags | Description |
---|---|---|---|
avg | Number | Required | The average value for the percentile. |
min | Number | Required | The minimum value for the percentile. |
max | Number | Required | The maximum value for the percentile. |
from | Integer | Required | The number of events that are on percentiles before the current one, plus 1. |
to | Integer | Required | The number of events that are on percentiles before the current one, plus the number of events that are on the current percentile. |
FieldDescription
An object that describes the available fields to be used in targeting rules, its types and also which fields can be used to group forecast results. Each key in the object represents the name of the field and maps to an array of strings or another array. The array should contain a string with the field type, i.e. either “string”, “numeric” or “boolean” and a string “groupable” if the field can be used to group forecast results. If the field is indexable, the array contains another array whose first element is the string “indexable” and the second element is an integer indicating the depth of the map (i.e., the number of keys to be supplied to reach an element of the indicated type). Therefore, the array should always have at most 3 elements (and at least 1).
Properties
Name | Type | Flags | Description |
---|---|---|---|
fieldName | Array of FieldProperty | Required | An array of properties for the given field. |
FieldProperty
A property of a field that can be used for targeting. Its type can be either a string or an array.
Rule
A string that represents a boolean expression, which should have the following format
key <operator> value
. Additionally, rules can be combined in the following formatrule <boolean operator> rule
.For more information about the rule syntax, check the Boolean Rules documentation.
TargetingRule
extends RuleA targeting rule is a string that represents a boolean expression that will be used when deciding if a given impressions is eligible for delivery for a given campaign. The rules operate on keys/fields (and respective values) that are available in the historical logs.
In addition to the fields that exist in the historical logs the following fields are provided by default:
Field Type localDate String (YYYY-MM-DD) hourOfDay Integer (0 to 23) dayOfWeek Integer (1 - Monday to 7 - Sunday) monthOfYear Integer (1 to 12) weekOfYear Integer (1 to 53) hasMasterUserId Boolean
GroupedFilteringRule
extends RuleA grouped filtering rule is a string that represents a boolean expression that will be used for filtering grouped results of a forecast result. The rules operate on keys/fields (and respective values) that should match the following subset of fields from GroupedCampaignForecast.
Field Type campaignId String impressions Integer uniqueUsers Integer lostImpressions Integer lostUniqueUsers Integer
ExistingTargetingRule
A JSON object representing a TargetingRule that is persisted on the server and can then be referenced (e.g. when defining a campaign).
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Required | Unique identifier of the targeting rule. |
rule | TargetingRule | Required | A string that represents a boolean expression. Quotes inside rules need to be escaped. |
TargetingRuleContainer
A JSON object containing either a TargetingRule or an id to reference an existing TargetingRule. Only one of the two fields should be defined (id or rule). When using a reference to an existing TargetingRule if the targeting rule doesn’t exist no error is given and instead the targeting rule is ignored.
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | Existing targeting rule ID. |
|
rule | TargetingRule | A string that represents a boolean expression. Quotes inside rules need to be escaped. |
ExistingCampaignsOverridesMap
An object that describes the campaigns to be overriden in the existing campaigns.
Each key in the object represents the id of the campaign to be overriden and maps to an object with the new field values.
This makes it possible to forecast what would happen if one or more campaigns stored in the system (via the
/campaigns
endpoint) were modified, without having to modify those campaigns.
Additional Properties ?
Type | Description |
---|---|
CampaignOverride | Campaign values to override. |
CampaignOverride
An object that describes the fields to be overriden in a given campaign.
Each key in the object represents a field name and maps to the new field value.
Properties
Name | Type | Flags | Description |
---|---|---|---|
startDate | String (date-time) | Start date of the campaign, as yyyy-mm-dd HH:MM:SS. |
|
endDate | String (date-time) | End date of the campaign, as yyyy-mm-dd HH:MM:SS. |
|
priority | Integer | Relative campaign priority, as used by the ad decision logic. Larger numbers correspond to higher priorities. |
|
weight | Number | Relative campaign weight, as used by the ad decision logic. |
|
impressions | Integer | The impression goal defined for the campaign (for the whole lifetime of the campaign). |
|
deliveredImpressions | Integer | Number of impressions already delivered for the given campaign. |
|
dailyCap | Integer | Maximum number of impressions to be delivered per day. |
|
frequencyCaps | Array of FrequencyCap | Array of frequency capping rules set for the campaign. |
|
targeting | Array of TargetingRuleContainer | The specified targeting for the campaign. |
|
retargeting | Array of String | IDs of the campaigns that this campaign is retargeting. |
|
useMasterUserId | Boolean | Whether to use a master user id (e.g. cross-device id) for unique user tracking and frequency capping. |
|
lastUpdate | String (date-time) | The time of the last update of this campaign’s definition, as a valid ISO8601 string (e.g. 2016-01-11T17:31:10+00:00).
It defines the date for which the current state of the campaign (i.e. |
Warning
A non-fatal warning message identified by a warning code. The possible warning codes are the following:
Code Meaning MODHNT The forecasted traffic has been modified by ForecasterHints CRTHNT Synthetic traffic was used due to unavailable training information OVRHNT Two or more ForecasterHints overlapped, which can have an undefined behavior IPLHNT Some existing impressions were overriden by a ForecasterHint NOLOGS Some campaigns start before or end after the available logs
Properties
Name | Type | Flags | Description |
---|---|---|---|
code | String | Required | The warning code. |
message | String | Required | A descriptive warning message. |
causes | Array of String | A list of resources causing this warning. |
Notification
A message pushed to clients over HTTP who have set the
notifyUrl
field when an asynchronous forecast finishes.
Properties
Name | Type | Flags | Description |
---|---|---|---|
id | String | The id of the forecast for which this notification relates. |
|
desc | String | A descriptive message of the notification. |