Contact support
    • Monetization
    • Developer documentation
    • Automate monetization

    Automate forecasting (API)

    Table of Contents

    Overview Login credentials API Documentation Base URL Authentication API limits Limits per UTC day Pagination of responses Criteria Resource Overview Fields Endpoint Example Representation Operations CriteriaValues Resource Overview Fields Endpoint Example Representation Operations Special criteria: BusinessException Forecast Resource Overview Example Output format Endpoint Example Representation Request Body Fields Dimensions Body Example Representation Operations Additional information Difference between forecast criteria and split result criteria Metric fields Types

    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).

    Base URL

    The Base URL for the API is:

    https://forecast.smartadserverapis.com/

    Authentication

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

    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
    PUT ONLINE (ID: 4) 2000
    READ (ID: 1) 20000
    WRITE  (ID: 2) 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
    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
    fields fields available for the criterion. Example: for the country criterion, fields = [CountryID, CountryName] string[]
    name name identifying the criterion string

    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
    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)
    value A possible value of the criterion. For example, for the criterion country, a value is simply a country ID. 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." }

    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. For more information, see Set keyword targeting.

    {
	"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
    capping Capping information for the forecast request. The supported capping types are: global, on visit and periodic (frequency). CappingConfiguration no
    criteriaCondition DEPRECATED. Strictly equivalent to filter. See filter no
    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 isautomatically limited to the maximum value.The timezone is the timezone defined in your network (account at Equativ). DateTime (ISO 8601) yes
    fields List of fields to include in the CSV as columns.By default, it is ["TotalImpressions","OccupiedImpressions","AvailableImpresssions"].The fields implicetely define thesplitting criteria. For example you add "FormatID" or "FormatName" to fields, the resultwill be split by format.Use the criteria resource to know the list of all possible fields. string[] no
    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
    highestPriorityConsideredAsAvailable Defines which insertions are considered as occupying volume.This field is the highest priority of an insertion not considered asoccupied (thus considered as available). Possible values are the same as usual insertion priorities.Use resource insertionpriorities onmanage.smartadserverapis.com to get the list. string no
    highestPriorityGroupConsideredAsAvailable Defines which insertions are considered as occupying volume. This field is the highest prioritygroup of an insertion not consideredas occupied (thus considered as available). Possible values are: "Exclusive","High", "Normal", "Low", "Complement" (default),"None". string no
    splittingCriteria DEPRECATED. Use fields. string[] no
    splittingKeys DEPRECATED. Use fields. string[] no
    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

    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. For more information, see Set 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": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024 for the whole network)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, for the siteID = 2727)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, on (France or London or North East England) and Desktop)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, on (France or London or North East England) and desktop and visit capping = 2)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, on France, split by platform)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, on France, split by keywords, keywords without key) :

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, on France, split by keywords, only for keyword with key “k”)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, to August 11, 2024, on France, split by day)

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

    CSV

    Day;TotalImpressions;OccupiedImpressions;AvailableImpressions
2024-08-08T00:00:00;17776;11110;6666
2024-08-09T00:00:00;16501;11005;5496
2024-08-10T00:00:00;18107;10998;7109
2024-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, 2024, split by insertion)

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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, 2024, split by Day, Format and Keyword "gender")

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

    CSV

    Day;FormatName;Keyword(gender);TotalImpressions
2024-08-08T00:00:00;Banner;gender=m;17776
2024-08-09T00:00:00;Banner;gender=m;16501
2024-08-10T00:00:00;Banner;gender=m;18107
2024-08-11T00:00:00;Banner;gender=m;17440
2024-08-08T00:00:00;Banner;gender=f;17776
2024-08-09T00:00:00;Banner;gender=f;16501
2024-08-10T00:00:00;Banner;gender=f;18107
2024-08-11T00:00:00;Rectangle;gender=f;17440
2024-08-08T00:00:00;Rectangle;gender=m;17776
2024-08-09T00:00:00;Rectangle;gender=m;16501
2024-08-10T00:00:00;Rectangle;gender=m;18107
2024-08-11T00:00:00;Rectangle;gender=m;17440
2024-08-08T00:00:00;Rectangle;gender=f;17776
2024-08-09T00:00:00;Rectangle;gender=f;16501
2024-08-10T00:00:00;Rectangle;gender=f;18107
2024-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.

    Metric 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
    AvailableImpressions Expected number of impressions that can still be used (sold). It is always TotalImpressions minus OccupiedImpressions.
    OccupiedImpressions Expected number of impressions considered as occupied : used by insertions with sufficiently high priority or impossible to use because of capping
    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.
    TotalImpressions Expected total number of impressions including insertions and no-ad

    Example

    {
  "startDate": "2024-08-08T00:00:00",
  "endDate": "2024-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
    periodInMinutes period of periodic capping as a number of minutes int required if periodic is not 0
    periodic periodic capping: maximum number of times a user can see the insertion in one period (see periodInMinutes) int no
    visit visit capping: maximum number of times a user can see the insertion in one visit int no

    RELATED ARTICLES