Ad Forecaster API

1.3 {adforecasterInstance}.api.adforecaster.com:9000 /v1.3 http Basic Authentication

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns -d '[{ "id": "61adea4", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "timeZone": "UTC", "priority": 1, "weight": 100, "impressions": 10000000, "deliveredImpressions": 13924, "dailyCap": 20000, "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "targeting": [ { "id": "c0384f1de" }, { "rule": "geoCountry = \"GB\"" } ], "retargeting": [ "d6274a5", "e797bcd" ], "lastUpdate": "2012-09-02T18:36:10Z" }]'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns/{id}

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns/{id} -d '{ "id": "61adea4", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "timeZone": "UTC", "priority": 1, "weight": 100, "impressions": 10000000, "deliveredImpressions": 13924, "dailyCap": 20000, "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "targeting": [ { "id": "c0384f1de" }, { "rule": "geoCountry = \"GB\"" } ], "retargeting": [ "d6274a5", "e797bcd" ], "lastUpdate": "2012-09-02T18:36:10Z" }'

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns/{id} -d '{ "id": "61adea4", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "timeZone": "UTC", "priority": 1, "weight": 100, "impressions": 10000000, "deliveredImpressions": 13924, "dailyCap": 20000, "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "targeting": [ { "id": "c0384f1de" }, { "rule": "geoCountry = \"GB\"" } ], "retargeting": [ "d6274a5", "e797bcd" ], "lastUpdate": "2012-09-02T18:36:10Z" }'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/campaigns/{id}

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups -d '[{ "id": "asdl23f", "campaignIds": [ "61adea4", "3dd6b6f", "92c99a6" ], "frequencyCap": { "nTimes": 2, "nMinutes": 120 } }]'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups/{id}

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups/{id} -d '{ "id": "asdl23f", "campaignIds": [ "61adea4", "3dd6b6f", "92c99a6" ], "frequencyCap": { "nTimes": 2, "nMinutes": 120 } }'

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups/{id} -d '{ "id": "asdl23f", "campaignIds": [ "61adea4", "3dd6b6f", "92c99a6" ], "frequencyCap": { "nTimes": 2, "nMinutes": 120 } }'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/frequency_groups/{id}

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints -d '[{ "id": "e123e48", "type": "multiplier", "startDate": "2012-09-03 00:00:00", "endDate": "2012-09-04 00:00:00", "multiplier": 2.0, "rule": "geoCountry = \"GB\"" }]'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints/{id}

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints/{id} -d '{ "id": "e123e48", "type": "multiplier", "startDate": "2012-09-03 00:00:00", "endDate": "2012-09-04 00:00:00", "multiplier": 2.0, "rule": "geoCountry = \"GB\"" }'

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints/{id} -d '{ "id": "e123e48", "type": "multiplier", "startDate": "2012-09-03 00:00:00", "endDate": "2012-09-04 00:00:00", "multiplier": 2.0, "rule": "geoCountry = \"GB\"" }'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/hints/{id}

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting -d '[{ "id": "1ffce3b7c", "rule": "geoCountry = \"GB\"" }]'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting/{id}

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting/{id} -d '{ "id": "1ffce3b7c", "rule": "geoCountry = \"GB\"" }'

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPUT {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting/{id} -d '{ "id": "1ffce3b7c", "rule": "geoCountry = \"GB\"" }'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/targeting/{id}

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast

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 no-cache the system ignores any cached result it might have.

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast -d '{ "newCampaigns": [ { "id": "campaign1", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "priority": 0, "targeting": [ { "id": "fcf0991d1" }, { "rule": "geoCountry = \"GB\"" } ], "weight": 100 }, { "id": "campaign2", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-05 23:59:59", "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "priority": 0, "weight": 100 } ], "plannedCampaigns": [ ], "frequencyGroups": [ { "id": "fg1", "campaignIds": [ "campaign1" ], "frequencyCap": { "nTimes": 2, "nMinutes": 0 } } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } }'

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/{id}

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/{id}

/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 no-cache the system ignores any cached result it might have.

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/available -d '{ "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "priority": 4, "targeting": [ { "id": "a934c9a" }, { "rule": "geoCountry = \"GB\"" } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } }'

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/available/{id}

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/available/{id}

/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 no-cache the system ignores any cached result it might have.

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
cURL Example
curl -u {username}:{password} -H "Content-Type:application/json" -XPOST {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/eligible -d '{ "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "targeting": [ { "id": "a934c9a" }, { "rule": "geoCountry = \"GB\"" } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } }'

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/eligible/{id}

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
cURL Example
curl -u {username}:{password} -XDELETE {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/eligible/{id}

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/existing_campaigns

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/info

/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
cURL Example
curl -u {username}:{password} -XGET {adforecasterInstance}.api.adforecaster.com:9000/v1.3/forecast/fields

MessageResponse

Properties

Name Type Flags Description
message String Required

System message.

warnings Array of Warning

Non-fatal warnings.

Example
{ "message": "New campaigns set." }

ErrorResponse

Properties

Name Type Flags Description
errorMessage String Required

Error message.

Example
{ "errorMessage": "Invalid campaign id in request body." }

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
Example
{ "id": "asdl23f", "campaignIds": [ "61adea4", "3dd6b6f", "92c99a6" ], "frequencyCap": { "nTimes": 2, "nMinutes": 120 } }

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.

Example
{ "nTimes": 2, "nMinutes": 120 }

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 existingCampaignsOverrides is defined then this one is not required.

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 request.hints[0] will be used, where the number represents the position of the hint in the array.

params ForecastRequestParams

Parameter settings for the forecast request

Example
{ "newCampaigns": [ { "id": "campaign1", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "priority": 0, "targeting": [ { "id": "fcf0991d1" }, { "rule": "geoCountry = \"GB\"" } ], "weight": 100 }, { "id": "campaign2", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-05 23:59:59", "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "priority": 0, "weight": 100 } ], "plannedCampaigns": [ ], "frequencyGroups": [ { "id": "fg1", "campaignIds": [ "campaign1" ], "frequencyCap": { "nTimes": 2, "nMinutes": 0 } } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } }

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. localDate, hourOfDay). Available time zones.

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.

Example
{ "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" }

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 hourOfDay > 10 assumes that the given hour is in “EST”.

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 request.hints[0] will be used, where the number represents the position of the hint in the array.

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 bookedByCampaign which controls whether to show results of booked impressions by existing campaign. The option countLostOpportunities is not interpreted when processing available forecast requests. Additionally, aggStats and rtbStats are currently not supported for this type of request.

Example
{ "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "priority": 4, "targeting": [ { "id": "a934c9a" }, { "rule": "geoCountry = \"GB\"" } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } }

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 hourOfDay > 10 assumes that the given hour is in “EST”.

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 request.hints[0] will be used, where the number represents the position of the hint in the array.

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 countLostOpportunities is not interpreted when processing eligible forecast requests as it relates to deliverability forecasts.

Example
{ "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "targeting": [ { "id": "a934c9a" }, { "rule": "geoCountry = \"GB\"" } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } }

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.

Example
{ "startDate": "2017-03-08", "endDate": "2017-09-08", "shardCount": 1024, "lastUpdate": "2017-03-08T16:34:48.501Z" }

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.

Example
{ "queued": 1, "executing": 1, "details": [ { "id": "da4a1038-1f32-4e8a-89de-b87b99779ee8", "type": "async", "status": "queued", "progress": 0.0, "desc": "The forecast is queued", "request": { "newCampaigns": [ { "id": "campaign1", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "priority": 0, "targeting": [ { "id": "fcf0991d1" }, { "rule": "geoCountry = \"GB\"" } ], "weight": 100 }, { "id": "campaign2", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-05 23:59:59", "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "priority": 0, "weight": 100 } ], "plannedCampaigns": [ ], "frequencyGroups": [ { "id": "fg1", "campaignIds": [ "campaign1" ], "frequencyCap": { "nTimes": 2, "nMinutes": 0 } } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } } } ] }

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.

Example
{ "id": "da4a1038-1f32-4e8a-89de-b87b99779ee8", "type": "async", "status": "queued", "progress": 0.0, "desc": "The forecast is queued", "request": { "newCampaigns": [ { "id": "campaign1", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "priority": 0, "targeting": [ { "id": "fcf0991d1" }, { "rule": "geoCountry = \"GB\"" } ], "weight": 100 }, { "id": "campaign2", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-05 23:59:59", "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "priority": 0, "weight": 100 } ], "plannedCampaigns": [ ], "frequencyGroups": [ { "id": "fg1", "campaignIds": [ "campaign1" ], "frequencyCap": { "nTimes": 2, "nMinutes": 0 } } ], "params": { "groupBy": [ "localDate" ], "filterGroupBy": "impressions > 1", "timeZone": "UTC", "sampling": 1, "rtbStats": true, "notifyUrl": "http://example.org/notify" } } }

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.

Example
{ "total": { "669c5b7e43": { "impressions": 6673951, "uniqueUsers": 2465928, "lostImpressions": 71772334, "lostUniqueUsers": 46138430, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } }, "grouped": [ { "key": { "localDate": "2012-08-16", "dayOfWeek": 6 }, "values": { "669c5b7e43": { "impressions": 6673951, "uniqueUsers": 2465928, "lostImpressions": 71772334, "lostUniqueUsers": 46138430, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } } } ], "groupedFiltered": { "669c5b7e43": { "impressions": 6673951, "uniqueUsers": 2465928, "lostImpressions": 71772334, "lostUniqueUsers": 46138430, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } }, "percentiles": { "clearingCpm": { "669c5b7e43": [ { "avg": 0.005, "from": 1, "max": 0.005, "min": 0.0038, "to": 48265 }, { "avg": 0.005, "from": 48266, "max": 0.005, "min": 0.005, "to": 96530 }, { "avg": 0.005, "from": 96531, "max": 0.005, "min": 0.005, "to": 144794 }, { "avg": 0.005, "from": 144795, "max": 0.005, "min": 0.005, "to": 193059 }, { "avg": 0.0053, "from": 193060, "max": 0.0063, "min": 0.005, "to": 241324 }, { "avg": 0.0077, "from": 241325, "max": 0.009, "min": 0.0063, "to": 289589 }, { "avg": 0.0104, "from": 289590, "max": 0.0122, "min": 0.009, "to": 337854 }, { "avg": 0.0148, "from": 337855, "max": 0.0191, "min": 0.0122, "to": 386118 }, { "avg": 0.0331, "from": 386119, "max": 0.0562, "min": 0.0191, "to": 434383 }, { "avg": 0.4213, "from": 434384, "max": 3.01, "min": 0.0562, "to": 482648 } ] } }, "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.

Example
{ "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "none", "progress": 0.0, "desc": "This forecast is still being processed" } { "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "partial", "progress": 93.75, "eta": "2016-01-19T12:22:07.790Z", "desc": "This forecast is still being processed. Partial results are available", "resultStatus": "success", "result": { "total": { "a5ec73": { "impressions": 17187, "uniqueUsers": 5049 } }, "warnings": [] } } { "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "finished", "progress": 100.0, "resultStatus": "success", "result": { "total": { "a5ec7": { "impressions": 15104, "uniqueUsers": 5048 } }, "warnings": [] } }

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.

Example
{ "total": { "booked": { "byCampaign": { "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "impressions": 6673951, "uniqueUsers": 2465928 }, "available": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "grouped": [ { "key": { "localDate": "2012-08-16", "dayOfWeek": 6 }, "values": { "booked": { "byCampaign": { "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "impressions": 6673951, "uniqueUsers": 2465928 }, "available": { "impressions": 6673951, "uniqueUsers": 2465928 } } } ], "groupedFiltered": { "booked": { "byCampaign": { "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "impressions": 6673951, "uniqueUsers": 2465928 }, "available": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "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.

Example
{ "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "none", "progress": 0.0, "desc": "This available forecast is still being processed" } { "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "partial", "progress": 93.75, "desc": "This available forecast is still being processed. Partial results are available", "resultStatus": "success", "result": { "total": { "booked": { "uniqueUsers": 824, "impressions": 824 }, "available": { "uniqueUsers": 1960, "impressions": 1960 } }, "warnings": [] } } { "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "finished", "progress": 100.0, "resultStatus": "success", "result": { "total": { "booked": { "uniqueUsers": 824, "impressions": 824 }, "available": { "uniqueUsers": 1960, "impressions": 1960 } }, "warnings": [] } }

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.

Example
{ "total": { "impressions": 6673951, "uniqueUsers": 2465928, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 }, "grouped": [ { "key": { "localDate": "2012-08-16", "dayOfWeek": 6 }, "value": { "impressions": 6673951, "uniqueUsers": 2465928, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } } ], "groupedFiltered": { "impressions": 6673951, "uniqueUsers": 2465928, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 }, "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.

Example
{ "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "none", "progress": 0.0, "desc": "This eligible forecast is still being processed" } { "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "partial", "progress": 93.75, "desc": "This eligible forecast is still being processed. Partial results are available", "resultStatus": "success", "result": { "total": { "impressions": 17187, "uniqueUsers": 5049 }, "warnings": [] } } { "id": "4ff3d5f9-d575-444e-82e7-188141bfd844", "status": "finished", "progress": 100.0, "resultStatus": "success", "result": { "total": { "impressions": 15104, "uniqueUsers": 5048 }, "warnings": [] } }

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 hourOfDay > 10 assumes that the given hour is in “EST”.

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. deliveredImpressions) refers to, so that the simulator can assume that the current number of delivered impressions were delivered between the campaign’s startDate and current lastUpdate. If deliveredImpressions is not 0 this field must be defined and must be equal or greater than the startDate.

Example
{ "id": "61adea4", "startDate": "2012-09-02 00:00:00", "endDate": "2012-09-07 23:59:59", "timeZone": "UTC", "priority": 1, "weight": 100, "impressions": 10000000, "deliveredImpressions": 13924, "dailyCap": 20000, "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "targeting": [ { "id": "c0384f1de" }, { "rule": "geoCountry = \"GB\"" } ], "retargeting": [ "d6274a5", "e797bcd" ], "lastUpdate": "2012-09-02T18:36:10Z" }

DeliverySchedule

A pacing strategy for a campaign.

Properties

Name Type Flags Description
type String with possible values:
  • asap
  • even
  • frontloaded
Required Discriminator

The type of delivery schedule.

Example
{ "type": "frontloaded", "percentage": 25.0 }

AsapDeliverySchedule

extends DeliverySchedule

A delivery schedule that attempts to deliver all impressions as soon as possible.

Example
{ "type": "asap" }

EvenDeliverySchedule

extends DeliverySchedule

A delivery schedule that attempts to deliver impressions evenly during the campaign lifetime.

Example
{ "type": "even" }

FrontloadedDeliverySchedule

extends DeliverySchedule

A delivery schedule that attempts to deliver impressions evenly with a bias during the campaign lifetime. For more information, check the Delivery Logic documentation.

Example
{ "type": "frontloaded", "percentage": 25.0 }

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:
  • multiplier
  • impressionCount
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 hourOfDay > 10 assumes that the given hour is in “EST”.

rule TargetingRule

Rule used to filter impressions. The hint will only be applied to impressions who conform to this rule.

Example
{ "id": "e123e48", "type": "multiplier", "startDate": "2012-09-03 00:00:00", "endDate": "2012-09-04 00:00:00", "multiplier": 2.0, "rule": "geoCountry = \"GB\"" }

MultiplierHint

extends ForecasterHint

A 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 the rule field, those impressions will be ignored and a IPLHNT 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).

Example
{ "id": "e123e48", "type": "multiplier", "startDate": "2012-09-03 00:00:00", "endDate": "2012-09-04 00:00:00", "multiplier": 2.0, "rule": "geoCountry = \"GB\"" }

ImpressionCountHint

extends ForecasterHint

A 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, a CRTHNT warning will be triggered. Note that this will only work if the inventoryPoolRule parameter is set or if the rule 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 the rule field, those impressions will be ignored and a IPLHNT 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).

Example
{ "id": "e123e49", "type": "impressionCount", "startDate": "2012-09-03 00:00:00", "endDate": "2012-09-04 00:00:00", "impressionCount": 100000, "rule": "geoCountry = \"GB\"" }

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.

Example
{ "clearingCpm": 0.0729 }

CampaignForecasts

Additional Properties ?

Type Description
CampaignForecastValues

The map of campaign ids to results.

Example
{ "669c5b7e43": { "impressions": 6673951, "uniqueUsers": 2465928, "lostImpressions": 71772334, "lostUniqueUsers": 46138430, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } }

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.

Example
{ "impressions": 6673951, "uniqueUsers": 2465928, "lostImpressions": 71772334, "lostUniqueUsers": 46138430, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 }

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.

Example
{ "key": { "localDate": "2012-08-16", "dayOfWeek": 6 }, "values": { "669c5b7e43": { "impressions": 6673951, "uniqueUsers": 2465928, "lostImpressions": 71772334, "lostUniqueUsers": 46138430, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } } }

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.

Example
{ "booked": { "byCampaign": { "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "impressions": 6673951, "uniqueUsers": 2465928 }, "available": { "impressions": 6673951, "uniqueUsers": 2465928 } }

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.

Example
{ "impressions": 6673951, "uniqueUsers": 2465928 }

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 bookedByCampaign is true).

Example
{ "byCampaign": { "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "impressions": 6673951, "uniqueUsers": 2465928 }

AvailableForecastCampaignValue

Additional Properties ?

Type Description
AvailableForecastValue

The map of campaign ids to results.

Example
{ "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }

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.

Example
{ "key": { "localDate": "2012-08-16", "dayOfWeek": 6 }, "values": { "booked": { "byCampaign": { "10000055": { "impressions": 6673951, "uniqueUsers": 2465928 } }, "impressions": 6673951, "uniqueUsers": 2465928 }, "available": { "impressions": 6673951, "uniqueUsers": 2465928 } } }

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.

Example
{ "impressions": 6673951, "uniqueUsers": 2465928, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 }

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.

Example
{ "key": { "localDate": "2012-08-16", "dayOfWeek": 6 }, "value": { "impressions": 6673951, "uniqueUsers": 2465928, "avg": { "clearingCpm": 0.0729 }, "peakRtbQueriesPerSecond": 42 } }

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.

Example
{ "localDate": "2012-08-16", "dayOfWeek": 6 }

PercentileResult

A set of results for each field given in aggStats and the clearing CPM (if rtbStats 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 aggStats.

Example
{ "clearingCpm": { "669c5b7e43": [ { "avg": 0.005, "from": 1, "max": 0.005, "min": 0.0038, "to": 48265 }, { "avg": 0.005, "from": 48266, "max": 0.005, "min": 0.005, "to": 96530 }, { "avg": 0.005, "from": 96531, "max": 0.005, "min": 0.005, "to": 144794 }, { "avg": 0.005, "from": 144795, "max": 0.005, "min": 0.005, "to": 193059 }, { "avg": 0.0053, "from": 193060, "max": 0.0063, "min": 0.005, "to": 241324 }, { "avg": 0.0077, "from": 241325, "max": 0.009, "min": 0.0063, "to": 289589 }, { "avg": 0.0104, "from": 289590, "max": 0.0122, "min": 0.009, "to": 337854 }, { "avg": 0.0148, "from": 337855, "max": 0.0191, "min": 0.0122, "to": 386118 }, { "avg": 0.0331, "from": 386119, "max": 0.0562, "min": 0.0191, "to": 434383 }, { "avg": 0.4213, "from": 434384, "max": 3.01, "min": 0.0562, "to": 482648 } ] } }

CampaignPercentileResult

The percentile results for each campaign.

Additional Properties ?

Type Description
Array of PercentileData

The percentiles for each campaign.

Example
{ "669c5b7e43": [ { "avg": 0.005, "from": 1, "max": 0.005, "min": 0.0038, "to": 48265 }, { "avg": 0.005, "from": 48266, "max": 0.005, "min": 0.005, "to": 96530 }, { "avg": 0.005, "from": 96531, "max": 0.005, "min": 0.005, "to": 144794 }, { "avg": 0.005, "from": 144795, "max": 0.005, "min": 0.005, "to": 193059 }, { "avg": 0.0053, "from": 193060, "max": 0.0063, "min": 0.005, "to": 241324 }, { "avg": 0.0077, "from": 241325, "max": 0.009, "min": 0.0063, "to": 289589 }, { "avg": 0.0104, "from": 289590, "max": 0.0122, "min": 0.009, "to": 337854 }, { "avg": 0.0148, "from": 337855, "max": 0.0191, "min": 0.0122, "to": 386118 }, { "avg": 0.0331, "from": 386119, "max": 0.0562, "min": 0.0191, "to": 434383 }, { "avg": 0.4213, "from": 434384, "max": 3.01, "min": 0.0562, "to": 482648 } ] }

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.

Example
{ "avg": 0.0331, "min": 0.0191, "max": 0.0562, "from": 1, "to": 434383 }

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.

Example
{ "city": [ "string", "groupable" ], "ip": [ "string" ], "dayOfWeek": [ "numeric", "groupable" ], "timestamp": [ "numeric" ], "hourOfDay": [ "numeric", "groupable" ], "browser": [ "string" ], "domain": [ "string" ], "country": [ "string", "groupable" ], "userAgent": [ "string" ], "longitude": [ "numeric" ], "region": [ "string", "groupable" ], "referrer": [ "string" ], "userId": [ "string" ], "localDate": [ "string", "groupable" ], "rendered": [ "boolean", "groupable" ], "keyValuePair": [ "string", [ "indexable", 1 ] ] }

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 format rule <boolean operator> rule.

For more information about the rule syntax, check the Boolean Rules documentation.

TargetingRule

extends Rule

A 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

Example
"geoCountry = \"GB\"" "publisherId in (\"31\",\"36\",\"40\")" "format = \"300×250\" || format = \"120×600\"" "rtbFloorPrice < 0.76" "userGender = \"M\" && ( userAge > 24 || userAge = 0 )"

GroupedFilteringRule

extends Rule

A 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

Example
"impressions > 1000" "impressions > 500 && uniqueUsers < 250" "lostImpressions < 100 && lostUniqueUsers < 100 || impressions >= 1000"

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.

Example
{ "id": "1ffce3b7c", "rule": "geoCountry = \"GB\"" }

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.

Example
{ "rule": "geoCountry = \"GB\"" }

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.

Example
61adea4: $ref: '#/definitions/CampaignOverride'

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. deliveredImpressions) refers to, so that the simulator can assume that the current number of delivered impressions were delivered between the campaign’s startDate and current lastUpdate. If deliveredImpressions is not 0 this field must be defined and must be equal or greater than the startDate.

Example
{ "endDate": "2012-09-07 23:59:59", "impressions": 10000000, "frequencyCaps": [ { "nTimes": 2, "nMinutes": 120 } ], "targeting": [ { "rule": "geoCountry = \"GB\"" } ] }

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.

Example
{"code": "MODHNT", "message": "Traffic modified by hints: country = \"FR\"", "causes": ["hint1"]} {"code": "CRTHNT", "message": "Artificial data created for: country = \"FR\"", "causes": ["hint1"]} {"code": "OVRHNT", "message": "Hint overlap at: { country = \"FR\", !(country = \"EN\") }"}, "causes": ["hint2"] {"code": "IPLHNT", "message": "Some existing impressions were overriden for: country = \"FR\"", "causes": ["hint1"]} {"code": "NOLOGS", "message": "Campaigns with start date/end date outside of the range of the processed/generated logs", "causes": ["campaign1"]}

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.

Example
{ "id": "d1f79884-c717-4156-b149-9635f42a39e7", "desc": "Forecast finished" }