Forecast API

Before you start, take a look at the general article on how to use Smart AdServer's REST WebAPI here.

Criteria Resource

Overview

The Criteria resource returns the list of all the criteria you can use in a given forecast request.

There are two several of criteria:

  • placement related criteria (format, site/page/pack)
  • targeting criteria (e. g. geolocation, OS, platform...)
  • time criteria (eg. day, hour...)
  • element criteria (eg : insertion)

Fields

A criterion contains the following fields:

Name Description Type
name name identifying the criterion string
fields fields available for the criterion. Example: for the country criterion, fields = [CountryID, CountryName] string[]
canFilter true if the criterion can be used as a filter criterion in the forecast request bool
canSplit true if the criterion can be used as a split criterion in the forecast request bool

Endpoint

https://forecast.smartadserverapis.com/<NETWORK_ID>/criteria/

Each of Smart AdServer's customers has an individual, static <NETWORK_ID>.

Example Representation

{
  "name":"Site",
  "fields":["SiteID","SiteName"],
  "canFilter": true,
  "canSplit": true
}

Operations

GET

https://forecast.smartadserverapis.com/73/criteria/

[
 {
  "name":"Site",
  "fields":["SiteID","SiteName"],
  "canFilter": true,
  "canSplit": true
 },
 {
  "name": "Day",
  "fields": ["Day"],
  "canFilter": false,
  "canSplit": true
 },
 {
  "name": "Format",
  "fields": ["FormatID", "FormatName"],
  "canFilter": true,
  "canSplit": true
 }
...
]

https://forecast.smartadserverapis.com/73/criteria/Site/

{
  "name":"Site",
  "fields":["SiteID","SiteName"],
  "canFilter": true,
  "canSplit": true
}

Other available GET urls

https://forecast.smartadserverapis.com/73/criteria?offset=10&limit=15
https://forecast.smartadserverapis.com/73/criteria?limit=10
https://forecast.smartadserverapis.com/73/criteria?offset=20

CriteriaValues Resource

Overview

The CriteriaValues resource returns the list of all the possible values for a given criterion.

Fields

Name Description Type
criterionName Name that identifies the criterion ("site", "format"...) string
value A possible value of the criterion. For example, for the criterion country, a value is simply a country ID. string
fields the contents of all the fields for this criterion value. The fields depend on the criterion. For example, for the country 184, the fields are {countryID : 184, countryName : France}. dictionary(string, string)

Endpoint

https://forecast.smartadserverapis.com/<NETWORK_ID>/criteria/<CRITERION_NAME>/values/

Example Representation

[
  {
    "criterionName":"Platform",
    "value":"1",
    "fields":{"platformID":"1","platformName":"Desktop"}
  },
  {
    "criterionName":"Platform",
    "value":"2",
    "fields":{"platformID":"2","platformName":"Tablet"}
  },
  {
    "criterionName":"Platform",
    "value":"3",
    "fields":{"platformID":"3","platformName":"Smartphone"}
  }
]

Operations

GET

https://forecast.smartadserverapis.com/73/criteria/platform/values/
[
  {
    "criterionName":"Platform",
    "value":"1",
    "fields":{"platformID":"1","platformName":"Desktop"}
  },
  {
    "criterionName":"Platform",
    "value":"2",
    "fields":{"platformID":"2","platformName":"Tablet"}
  },
  {
    "criterionName":"Platform",
    "value":"3",
    "fields":{"platformID":"3","platformName":"Smartphone"}
  }
]

Other available GET urls

https://forecast.smartadserverapis.com/73/criteria/platform/values?offset=40&limit=15
https://forecast.smartadserverapis.com/73/criteria/platform/values?limit=10
https://forecast.smartadserverapis.com/73/criteria/platform/values?offset=20

Special criteria: BusinessException

The following criteria are only used for splitting results during the forecast request:

  • Time related criteria, e. g. Day, Hour or Month
  • Element criteria, e. g. Insertion or Campaign

These criteria are neither placement nor targeting related. They have no defined values. Thus, requests of this type will fail and will trigger a BusinessException.

Example of BusinessException (requesting the Day criterion):

{ "name": "BusinessException", "message": "Criterion foo could not be interpreted." }.

Differences between the user interface and forecast web APIs

Forecast Resource

Overview

The forecast resource estimates your future inventory. It returns the available, occupied and total volumes (in impressions). You can specify the criteria for time period, capping, placements and targeting in your queries (read above for more about the criteria).

You can get the forecast results split (broken down) by the values of some specific criteria. If you do not provide any splitting criterion, you will receive only one single forecast result. If you specify a splitting criterion in the property "fields", there will be as many forecast results as there are possible values for the splitting criterion (see above for more about CriteriaValues). You can also split by the values serveral criteria.

Output format

The results are returned as a CSV file with the following content:

  • the first line; invariably contains the headers; these specify the information contained in each column
  • the following lines; contain the actual forecast volumes (available, booked and total)
  • splitting information; only if a splitting criterion has been specified in the request; splitting information are the values of splitting criteria;

Endpoint

You obtain the CSV results in 3 steps:

1. Do a POST request as follows:

https://forecast.smartadserverapis.com/<NETWORK_ID>/forecast/


=> The response is instant and contains a "Location" header with a link to the forecast request status, e.g.

https://forecast.smartadserverapis.com/XXX/forecast/4facb5af-ec11-4bad-9bf0-XXXXXXXXX

2. Do a GET request with this received URL

You will first receive:

"{"status":"Pending"}"

After a few moments, you will receive:

"{"status":"Available"}"

At this point, check the response headers: again, you will find a "Location" header; this header includes the URL of the final CSV.

3. Obtain the CSV file at the specified URL

Example Representation

PlatformID;TotalImpressions;OccupiedImpressions;AvailableImpressions
1;7777;4444;3333
2;4444;3333;1111
3;5555;3333;2222
N/A;2224;890;1334

Note: In the example above, the separator of the CSV file is ";".

Request Body Fields

Name Description Type Mandatory
startDate Start date of the forecast request.
The minimum date is when the
forecast was last computed.
If the provided date is before,
it is automatically limited to
this minimum value.
The timezone is the timezone
defined in your network
(account at Smart AdServer).
DateTime
(ISO 8601)
yes
endDate End date of the forecast request.
The maximum date is the end of the
forecast period: last computation +
the number of months for which the
forecast is enabled.
If the provided date is later, it is
automatically limited to the maximum value.
The timezone is the timezone
defined in your network
(account at Smart AdServer).
DateTime
(ISO 8601)
yes
filter Array of criteria groups.
Each group is a dictionary
containing one or more pair(s)
of (field,value[]).
A group is always an OR-connection
between criteria in the same
dimension (read below for more about dimensions).
Groups are always AND-connected.
dictionary
(string,string[])[].
See examples below.
no
capping Capping information for the forecast request.
The supported capping types are:
global, on visit and periodic (frequency).
Capping
Configuration
no
fields List of fields to include in the
CSV as columns.By default, it is
["TotalImpressions",
"OccupiedImpressions",
"AvailableImpresssions"].
The fields implicetely define the
splitting criteria.
For example you add "FormatID" or
"FormatName" to fields, the result
will be split by format.
Use the criteria resource to know the
list of all possible fields.
string[] no
highest
PriorityGroup
Considered
AsAvailable
Defines which insertions are
considered as occupying volume.
This field is the highest priority
group of an insertion not considered
as occupied (thus considered as available).
Possible values are: "Exclusive",
"High", "Normal", "Low",
"Complement" (default),
"None".
string no
highestPriority
Considered
AsAvailable
Defines which insertions are
considered as occupying volume.
This field is the highest priority
of an insertion not considered as
occupied (thus considered as available).
Possible values are the same as
usual insertion priorities.
Use resource insertionpriorities on
manage.smartadserverapis.com to get the list.
string no
criteriaCondition DEPRECATED. Strictly equivalent to filter. See filter no
splittingCriteria DEPRECATED. Use fields. string[] no
splittingKeys DEPRECATED. Use fields. string[] no

Dimensions

A dimension is a group of criteria related to the same type of targeting. Within the same dimension, the criteria are OR-connected, while the dimensions themselves are AND-connected with each other.

As a general rule, each criterion represents a dimension. For instance the criterion "format" is a dimension for itself. However, some dimensions contain multiple criteria (criteria are noted in brackets).

  • Placement (Page, Site, Pack)
  • Geotargeting (City, State, Region, Country)
  • Device targeting (MobileVendor, MobileModel)
  • Keyword dimension (Keywords for the same key, e. g.: k1=v1 OR k1=v2 OR k1=v3), read more below

About keyword dimensions

Keywords can always be connected with OR or AND. Thus, you can use as many keyword dimensions as needed. The only restriction is that all the keywords in the same dimension must have the same key. However you can use the same key in several dimensions. Read here for more about keyword targeting.

Example

Assume you need the forecast results for the following criteria:

  • on format “banner” or “rectangle”

  • on site “foo.com” or pack “goo”

  • in France, Spain or Los Angeles

  • male users (keyword targeting sex=m)

  • users between 20 and 25 (keyword targeting age=20 or age=21… or age=25)


The following list shows the dimensions, into which you need to organize these criteria. Each dimension is followed by its criteria values (noted in brackets):

  • Format (banner or rectangle)
  • Placement (site “foo.com” or pack “goo”)
  • Geotargeting (France or Spain or Los Angeles)
  • Keyword sex (sex=m)
  • Keyword age (age=20 or age=21… or age=25)

Value of filter in the request body:

"filter": [
    {
      "FormatID": ["126","253"]
    },
    {
      "SiteID": ["55"],
      "PackID": ["69"]
    },
    {
      "CountryID": ["184","228”],
      "CityID": ["17284"]
    },
    {
      "Keyword": [“sex=m"]
    },
    {
      "Keyword": ["age=20”,"age=21","age=22","age=23","age=24","age=25"]
    }
  ]

Body Example Representation

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter": [
    {
      "CountryID": ["184"],
      "RegionID": ["164”,”113"]
    },
    {
      "PlatformID": ["1"]
    }
  ],
  "capping": {
    "global": 2,
    "visit": 0,
    "periodic": 0,
    "periodInMinutes": 0
  },
  "fields": ["Day","TotalImpressions","OccupiedImpressions","AvailableImpressions"]
}

Operations

POST

Example 1: whole network

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015 for the whole network)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00"
}

CSV

TotalImpressions;OccupiedImpressions;AvailableImpressions
9999;6666;3333

 

Example 2: one site

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, for the siteID = 2727)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter":[
    {
      "SiteID": ["2727"]
    }
  ]
}

CSV

TotalImpressions;OccupiedImpressions;AvailableImpressions
9000;6000;3000

 

Example 3: geotargeting and platform

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, on (France or London or North East England) and Desktop)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter": [
    {
      "CountryID": ["184"],
      "RegionID": ["164","113"]
    },
    {
      "PlaformID": ["1"]
    }
  ]
}

CSV

TotalImpressions;OccupiedImpressions;AvailableImpressions
6666;4444;2222

 

Example 4: capping

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, on (France or London or North East England) and desktop and visit capping = 2)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter": [
    {
      "CountryID": ["184"],
      "RegionID": ["164","113"]
    },
    {
      "PlatformID": ["1"]
    }
  ],
  "capping": {
    "Visit": 2
  }
}

CSV

TotalImpressions;OccupiedImpressions;AvailableImpressions
3333;2222;1111

 

Example 5: split by platform

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, on France, split by platform)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter": [
    {
      "CountryID": ["184"]
    }
  ],
  "fields": ["PlatformID","TotalImpressions","OccupiedImpressions","AvailableImpressions"]
}

CSV

PlatformID;TotalImpressions;OccupiedImpressions;AvailableImpressions
1;7777;4444;3333
2;4444;3333;1111
3;5555;3333;2222
N/A; 2224;890;1334

 

Example 6: split by keyword (keywords without key)

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, on France, split by keywords, keywords without key) :

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter": [
    {
      "CountryID": ["184"]
    }
  ],
  "fields": ["Keyword","TotalImpressions","OccupiedImpressions","AvailableImpressions"]
}

CSV

Keyword;TotalImpressions;OccupiedImpressions;AvailableImpressions
v1;6666;3333;3333
v2;2222;1111;1111
v3;6666;5555;1111
p1;346;301;45
p2;1100;800;300
t1;500;380;120
w1;250;20;230
w2;500;400;100
N/A; 2250;500;1750

 

Example 7: split by keyword (key “k”)

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, on France, split by keywords, only for keyword with key “k”)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "filter": [
    {
      "CountryID": ["184"]
    }
  ],
  "fields": ["Keyword(k)","TotalImpressions","OccupiedImpressions","AvailableImpressions"]
}

 

CSV

Keyword(k);TotalImpressions;OccupiedImpressions;AvailableImpressions
k=v1;6666;3333;3333
k=v2;2222;1111;1111
k=v3;6666;5555;1111
N/A;4446;2001;2445

 

Example 8: split by day

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on the period from August 8, 2015, to August 11, 2015, on France, split by day)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-12T00:00:00",
  "filter": [
    {
      "CountryID": ["184"]
    }
  ],
  "fields": ["Day","TotalImpressions","OccupiedImpressions","AvailableImpressions"]
}

 

CSV

Day;TotalImpressions;OccupiedImpressions;AvailableImpressions
2015-08-08T00:00:00;17776;11110;6666
2015-08-09T00:00:00;16501;11005;5496
2015-08-10T00:00:00;18107;10998;7109
2015-08-11T00:00:00;17440;10900;6540

 

Example 9: split by insertion

You may want to split your result by insertion to retrieve the delivered impressions for each insertion.  

Note : when using the exclusive link feature, some placements are forced to remain empty (no ad delivered). The forecast request result will display the blocked volumes as occupied for each format associated to an exclusive link.  If a format is forced to be empty, the volume will be returned with an insertionID "N/A" but occupying impressions. To know what exclusive link caused this volume to be occupied, add "LinkID" to "fields" in the body of the forecast request.

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8, 2015, split by insertion)

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-09T00:00:00",
  "fields": ["InsertionID","TotalImpressions","OccupiedImpressions","AvailableImpressions"]
}

CSV

InsertionID;TotalImpressions;OccupiedImpressions;AvailableImpressions
N/A;1280;0;1280       //Note : no-ad
540485;1000;0;1000    //Note : this insertion has a priority too low to be considered as occupying iventory
N/A;5607;5607;0       //Note : this volume is blocked by exclusive links
5524958;545;545;0     //Note : premium insertion

 

Example 10: Multi-criteria split

https://forecast.smartadserverapis.com/73/forecast

Data Body (forecast on August 8 to 11, 2015, split by Day, Format and Keyword "gender")

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-12T00:00:00",
  "fields": ["Day","FormatName","Keyword(gender)","TotalImpressions"]
}

CSV

Day;FormatName;Keyword(gender);TotalImpressions
2015-08-08T00:00:00;Banner;gender=m;17776
2015-08-09T00:00:00;Banner;gender=m;16501
2015-08-10T00:00:00;Banner;gender=m;18107
2015-08-11T00:00:00;Banner;gender=m;17440
2015-08-08T00:00:00;Banner;gender=f;17776
2015-08-09T00:00:00;Banner;gender=f;16501
2015-08-10T00:00:00;Banner;gender=f;18107
2015-08-11T00:00:00;Rectangle;gender=f;17440
2015-08-08T00:00:00;Rectangle;gender=m;17776
2015-08-09T00:00:00;Rectangle;gender=m;16501
2015-08-10T00:00:00;Rectangle;gender=m;18107
2015-08-11T00:00:00;Rectangle;gender=m;17440
2015-08-08T00:00:00;Rectangle;gender=f;17776
2015-08-09T00:00:00;Rectangle;gender=f;16501
2015-08-10T00:00:00;Rectangle;gender=f;18107
2015-08-11T00:00:00;Rectangle;gender=f;17440

 

Additional information

Difference between forecast criteria and split result criteria

See also: Special criteria: BusinessException

The criteria resource provides a list of useful criteria. Some of them are targeting criteria: you can specify their values in the filter inside the body of the forecast request.

Some other criteria are only used for splitting the results. These criteria cannot be used in the criteria object of the forecast request. If you try to do so, your forecast request will fail.

The following criteria fall within this scope :

  • Time criteria (e. g. Day, Hour
)
  • Element criteria (e. g. Insertion
)

To know which criteria can be used in filter and which criteria can be used for splitting, see the value of the fields canFilter and canSplit in the criteria resource.

Metrics fields

Fields can be either about criteria (such as FormatID and FormatName) or metrics. By default the three metrics "TotalImpressions", "OccupiedImpressions" and "AvailableImpressions" are returned. By you can ask for other metrics. Simply add them to the property "fields" in the body of the forecast request.

Name Description
TotalImpressions Expected total number of impressions including insertions and no-ad
OccupiedImpressions Expected number of impressions considered as occupied : used by insertions with sufficiently high priority or impossible to use because of capping
AvailableImpressions Expected number of impressions that can still be used (sold). It is always TotalImpressions minus OccupiedImpressions.
Revenue Expected revenue for existing insertions. Note : you need to define the financial data for your insertions to get meaningful results. (Excludes Smart RTB+ impressions)
RTBImpressions Expected number of Smart RTB+ impressions.
RTBRevenue Expected revenue for Smart RTB+ insertions.

Example

{
  "startDate": "2015-08-08T00:00:00",
  "endDate": "2015-08-12T00:00:00",
  "fields": ["Day","RTBImpressions","RTBRevenue"]
}

Types

Capping configuration

Name Description Type Mandatory
global global capping: maximum number of times a user can see the insertion int no
visit visit capping: maximum number of times a user can see the insertion in one visit int no
periodic periodic capping: maximum number of times a user can see the insertion in one period (see periodInMinutes) int no
periodInMinutes period of periodic capping as a number of minutes int required if periodic is not 0
Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk