Information

Title	Forecast API

URL Name	Forecast-API

Details

Article Body

Overview

With the Forecast API, you can retrieve predictions about the inventory available for sale in a future time range.

Login credentials

Reach out to your contact at Equativ to get your login credentials. There is no need to set up a test login. You will get a login for use in production right away.

API Documentation

Click here and select Forecast API to access the Forecast API documentation (the link also provides access to the documentation of the Manage API and RTB API).

Authentication

For information about how to authenticate, refer to the API authentication article.

Base URL

The Base URL for the API is:

https://forecast.smartadserverapis.com/

API limits

To prevent API performance issues by intended or accidental large scale operations, the API is subject to limits.

Limits per UTC day

Limits apply to the UTC day, not to the last 24 hours.
For instance, if you are doing an API call in France (UTC+2, summer time) at 01:00 AM on a Tuesday, the call will be counted for the Monday before, at 11:00 PM.

Action	Limit per UTC day
READ (ID: 1)	20000
WRITE (ID: 2)	2000
PUT ONLINE (ID: 4)	2000

Note that the limits above apply to the Forecast API, Manage API and RTB API globally.

Pagination of responses

API responses are paginated with each page holding a maximum of 100 items. The pagination information is sent in the response headers.

The response header X-Pagination-Total-Count contains the total amount of items matching your request. If this total exceeds 100, the response headers will also contain information to retrieve the next page and the previous pages.

The "Link" response header contains the link to the next page: <NextPageUrl>; rel="next"

To retrieve the next page’s results, make the same request again (using the same headers and body), but replace the called url with the value of <NextPageUrl>.

If a page has a previous page, the "Link" response header contains the link to the previous page: <PreviousPageUrl>; rel="prev"

If a page has both a previous and a next page, the "Link" response header contains both links, separated by a comma (,).

To customize the page size (max. number of items per page), add the "limit" parameter in the called URL. The value must not exceed 100.

Example for a request with a page size of 10 items:

https://forecast.smartadserverapis.com/forecast/?offset=10&limit=10

Example response headers:

X-Pagination-Total-Count: 89
Link: <https://forecast.smartadserverapis.com/XXX/forecast/?offset=20&limit=10>; rel="next", <https://forecast.smartadserverapis.com/forecast/?offset=0&limit=10>; rel="prev"

Note: Calls which always return a single item are not concerned.

Criteria Resource

Overview

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

There are several types 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 Equativ customer 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).

Example

The following code will return the total, occupied and available volume on the sites 11111 and 22222, with the format 33333 and the keyword key=value, with the results will be split by pageId. Learn more about keyword targeting here.

{
	"fields": [,
		"PageId",
		"TotalImpressions",
		"OccupiedImpressions",
		"AvailableImpressions"
	],
	"startDate": "2023-04-29T00:00:00",
	"endDate": "2023-04-29T23:59:59",
	"filter": [
		{
			"SiteID": [
				"11111",
				"22222"
			]
		},
		{
			"FormatID": [
				"33333"
			]
		},
		{
			"Keyword": [
				"key=value"
			]
		}
	]
}

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 Equativ).	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 Equativ).	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 more about keyword targeting here.

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

Using IsInsertionForecastOutdated as a splitting criterion is not recommended; if used, an error will occur when sending a GET request with location header afterwards.

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. But 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 Equativ RTB+ impressions)
RTBImpressions	Expected number of Equativ RTB+ impressions.
RTBRevenue	Expected revenue for Equativ 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

Notes