Page tree


Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added Metrics & Dimensions

Table of Contents
indent20px
stylenone



Warning
Before using PubMatic APIs, first generate the API Token. For more information, refer to  Getting Started with PubMatic APIs .  

Description

The Forecast API is used to retrieve Forecast data for future dates for given AdUnits and LineItems.

Supported Operations

For more information about UAS Ad Forecaster Services, refer to Ad Forecaster Services (UAS)

Service Name: /forecaster/

Method PathHTTP MethodDescriptionLink to Definition
/forecastGETUse to retrieve Forecast data for requested AdUnitIds with given filtering criteria. This API supports all possible dimensions except LineItem. The endpoint is likely to be consumed by Forecaster UI.Forecast Data for AdUnits
/forecast/downloadGETUse to download Forecast data in xls or csv format. Possible values of this parameters are "xls" and "csv."Download Forecast Data
/forecast/lineItemsGETUse to retrieve Forecast data for existing Line Item Ids. This API supports all possible dimensions except LineItem, as the response will already be grouped by LineItem Id.Forecast Data for Existing LineItems
/forecast/eligibleGETUse to retrieve eligible Forecast data for all AdUnitIds for a particular account and for a given period.Retrieving Eligible Forecast Data
/forecast/availsPOSTUse to get 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. This endpoint will also provide information about competing line items.Forecasting while creating a Line Item

Forecast Data for Ad Units

Overview

This API enables you to retrieve Forecast data for requested Ad Unit Ids with filtering criteria. This API supports all possible dimensions except Line Item. The endpoint is likely to be consumed by Forecaster UI.

This endpoint is used to get  Available Impressions  and Booked Impressions for given AdUnit Ids.


Info
See Supported Dimensions/Metrics/Operators for more details.

Request

           


Request Headers

                        

Header nameType ValueRequiredDescription
accountIdNumericExample: 34447YesAccount Id that has permission to get the Forecasting Report.
pubTokenString

${access_token}

Example: ae45ghj

Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.


For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                                                                           

Parameter NameTypeValidationsDescriptions
fromDateString Date in  ISO 8601  format, as per dimensions preferred. Start date for fetching the data. Forecast API will not support forecasting for more than six months into the future.
toDateString Date in  ISO 8601  format, as per dimensions preferred. End date for fetching data.Forecast API will not support forecasting for more than six months into the future.
metricsStringComma-separated list of metrics specified in the supported metrics list.

A list of comma-separated metrics such as Total Impressions, Unique Users etc.

If metrics are not present in the query, we will provide you data against all available metrics.See Here

dimensionsStringComma-separated list of dimensions specified in the supported dimensions list.

A list of comma-separated dimensions such as PUB ID, Site ID, etc. You can query with maximum 5 dimensions in single call.

If dimensions is not present in the query, we will provide you data against the date only.See Here

sortStringComma-separated list of dimensions or metrics present in the query parameters.

A list of comma-separated dimensions / metrics keys indicating the sorting fields and sorting order.

If sort key not found in requested query either in dimension or metrics, you will get an Bad Request response along with error code INVALID_SORT_KEY.

filtersString Refer to the filter section in the document for the filter syntax and the supported filter operations.
pageNumberIntegerPage number to get data for a particular page.
Default value = 1.
Page number to get data for a particular page.
pageSizeIntegerNumber of records to fetch on a specific page number. If Page Size is not specified, the default value will be 100.

Indicates the number of records returned from the API on specific page.

Note: If Page Number and Page Size both are not mentioned in request then Page Number will be set as default value 1 and Page Size will be equal to Total Records.

adUnitIdsIntegerComma-separated list of Ad Unit Ids for a Line Item for which forecasting data is required.

Comma separated list of Ad Unit Ids for an existing Line Item or a Line Item yet to be created.

If no Ad Unit Ids are passed, the corresponding request is considered for "Run of Networks."

priorityIntegerPriority of the Line Item being created.

Priority = -1 with no goal will give Avails,Booked Impressions. Total=Avails+booked impressions

Priority= 0 and goal= 1=Total Forecasted Delivered Impression

goalFloatValue to get Forecasted Available and lost impressionsPossible value can be between 0 to 1.

Sample Request URL

Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/forecaster/forecast?fromDate=2016-08-30&toDate=2016-08-31&dimensions=adUnitId,date&metrics=totalImpressions,bookedImpressions&filters=platformId eq 1&priority=-1&adUnitIds=932

Response

Response Fields

                  

Property NameValueDescription
columns[]ListComma separated name of the dimensions/metrics
rows[]ListEach row contains a lists of dimension values followed by the metric values. The order of dimensions and metrics is the same as specified in the request.


Sample Response JSON

    

Code Block
languagejs
linenumberstrue
{
  "metadata": {
    "pageNumber": 1,
    "pageSize": 2,
    "totalRecords": 2,
    "request": null
  },

  "columnHeaders": [
    "adUnitId",
    "adUnitName",
    "date",
    "totalImpressions",
    "bookedImpressions"

  ],

  "rows": [

    [

      "932",
      "Telephone_Creative_AU",
      "2016-08-30",
      2414284,
      2414024
    ],

    [

      "932",
      "Telephone_Creative_AU",
      "2016-08-31",
      2405444,
      2405444
    ]

  ]

}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Download Forecast Data

Overview

This API enables you to download Forecast data in xls or csv format. The "exportType" query parameter in the URI, which can have the possible parameters of "xls" or "csv," must be provided for download.

Request

           


Request Headers

                        

Header nameType ValueRequiredDescription
accountIdNumericExample: 34447YesAccount Id that has permission to get the Forecasting Report.
pubTokenString

${access_token}

Example: ae45ghj

Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.


For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                                                                           

Parameter NameTypeValidationsDescriptions
fromDateString Date in  ISO 8601  format, as per dimensions preferred. Start date for fetching the data. Forecast API will not support forecasting for more than six months into the future.
toDateString Date in  ISO 8601  format, as per dimensions preferred. End date for fetching data.Forecast API will not support forecasting for more than six months into the future.
metricsStringComma-separated list of metrics specified in the supported metrics list.

A list of comma-separated metrics such as Total Impressions, Unique Users etc.

If metrics are not present in the query, we will provide you data against all available metrics. See Here

dimensionsStringComma-separated list of dimensions specified in the supported dimensions list.

A list of comma-separated dimensions such as Pub ID, Site ID, etc. You can query with maximum 5 dimensions in single call.

If dimensions is not present in the query, we will provide you data against the date only.See Here

sortStringComma-separated list of dimensions or metrics present in the query parameters.

A list of comma-separated dimensions / metrics keys indicating the sorting fields and sorting order.

If sort key not found in requested query either in dimension or metrics, you will get an Bad Request response along with error code INVALID_SORT_KEY.

filtersString Refer to the filter section in the document for the filter syntax and the supported filter operations.
pageNumberIntegerPage number to get data for a particular page.
Default value = 1.
Page number to get data for a particular page.
pageSizeIntegerNumber of records to fetch on a specific page number. If Page Size is not specified, the default value will be 100.

Indicates the number of records returned from the API on specific page.

Note: If Page Number and Page Size both are not mentioned in request then Page Number will be set as default value 1 and Page Size will be equal to Total Records.

adUnitIdsIntegerComma-separated list of Ad Unit Ids for a Line Item for which forecasting data is required.

Comma separated list of Ad Unit Ids for an existing Line Item or a Line Item yet to be created.

If no Ad Unit Ids are passed, the corresponding request is considered for "Run of Networks."

priorityIntegerPriority of the Line Item being created.

Priority = -1 with no goal will give Avails,Booked Impressions. Total=Avails+booked impressions

Priority=0 and goal=1=Total Forecasted Delivered Impression

goalFloatValue to get Forecasted Available and lost impressionsPossible value can be between 0 to 1.

Sample Request URL


Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/forecaster/forecast/download?fromDate=2016-08-30&toDate=2016-08-31&dimensions=adUnitId,date&metrics=totalImpressions,bookedImpressions&priority=0&goal=1&adUnitIds=932&exportType=csv


Response

Sample Response JSON

    

Code Block
languagejs
linenumberstrue
"adUnitId","adUnitName","date","totalImpressions","bookedImpressions"

"932","Telephone_Creative_AU","2016-08-30","2414284","2414024"

"932","Telephone_Creative_AU","2016-08-31","2405444","2405444"‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Forecast Data for Existing LineItems

Overview

This API enables you to retrieve Forecast data for existing Line Item Ids. This API supports all possible dimensions (except Line Item as the response will already be grouped by Line Item Id), however, no filtering can be applied as the endpoint provides Forecasting data for the lifetime of requested Line Items. Use this API to retrieve Forecasted Eligible Inventory for the given Ad Unit Ids (to be consumed by Allocation Engine).

Request

           


Request Headers

                        

Header nameType ValueRequiredDescription
accountIdNumericExample: 34447YesAccount Id that has permission to get the Forecasting Report.
pubTokenString

${access_token}

Example: ae45ghj

Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.


For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                                                                           

Parameter NameTypeValidationsDescriptions
fromDateString Date in  ISO 8601  format, as per dimensions preferred. Start date for fetching the data. Forecast API will not support forecasting for more than six months into the future.
toDateString Date in  ISO 8601  format, as per dimensions preferred. End date for fetching data.Forecast API will not support forecasting for more than six months into the future.
metricsStringComma-separated list of metrics specified in the supported metrics list.

A list of comma-separated metrics such as Total Impressions, Unique Users etc. See Here

dimensionsStringComma-separated list of dimensions specified in the supported dimensions list.

A list of comma-separated dimensions such as Pub ID, Site ID, etc. You can query with maximum 5 dimensions in single call.

If dimensions is not present in the query, we will provide you data against the date only. See Here

sortStringComma-separated list of dimensions or metrics present in the query parameters.

A list of comma-separated dimensions / metrics keys indicating the sorting fields and sorting order.

If sort key not found in requested query either in dimension or metrics, you will get an Bad Request response along with error code INVALID_SORT_KEY.

filtersString Refer to the filter section in the document for the filter syntax and the supported filter operations.
pageNumberIntegerPage number to get data for a particular page.
Default value = 1.
Page number to get data for a particular page.
pageSizeIntegerNumber of records to fetch on a specific page number. If Page Size is not specified, the default value will be 100.

Indicates the number of records returned from the API on specific page.

Note: If Page Number and Page Size both are not mentioned in request then Page Number will be set as default value 1 and Page Size will be equal to total Records.

lineItemsIntegerComma-separated list of Line Item Ids for which forecasting data is required.Line Item Ids for which forecasting data is required.
priorityIntegerPriority of the Line Item being created.

Priority = -1 with no goal will give Avails,Booked Impressions. Total=Avails+booked impressions

Priority=0 and goal=1=Total Forecasted Delivered Impression

goalFloatValue to get Forecasted Available and lost impressionsPossible value can be between 0 to 1.

             

Supported Metrics

         

NameType DescriptiontotalImpressionsNumericTotal forecasted ImpressionsbookedImpressionsNumeric

Total booked impressions by already running Campaigns

bookedPercentageNumericBooked percentage out of total impressionsavailableImpressionsNumericTotal available impressions excluding the booked onesavailablePercentageNumericAvailable percentage out of total impressions

Supported Dimensions

         

NameType DescriptiondateDateGrouped by Date of Line ItemhourNumeric

Grouped by Hour on each date

adSizeId
NumericGrouped by adSizeIdplatformId
NumericGrouped by platformIdlineItemIdNumericLine Item Id is present by defaultlineItemNameNumericLine Item Name is present by defaultudidTypeIdNumericGrouped by udidTypeIdosIdNumericGrouped by osIdbrowserIdNumericGrouped by browserIdconnectionTypeIdNumericGrouped by connectionTypeIddeviceTypeIdNumericGrouped by deviceTypeIdcountryId
NumericGrouped by countryIdcarrierIdNumericGrouped by carrierIdrenderedBooleanWhether Ad was rendered or notaccountIdNumericAccount Id of Line ItemadUnitIdNumericAdUnits targeted by Line Item

Sample Request URL

https://api.pubmatic.com/v1/forecaster/forecast/lineItems?dimensions=adUnitId,date&metrics=totalImpressions&lineItems=27… 

Response

Response Fields

                  

Property NameValueDescription
columns[]ListComma separated name of the dimensions/metrics
rows[]ListEach row contains a lists of dimension values followed by the metric values. The order of dimensions and metrics is the same as specified in the request.


Sample Response JSON

    

Code Block
languagejs
linenumberstrue
{
  "metadata": {
    "pageNumber": 1,
    "pageSize": 13,
    "totalRecords": 13,
    "request": null
  },

  "columnHeaders": [
    "adUnitId",
    "adUnitName",
    "date",
    "totalImpressions",
    "lineItemId",
    "lineItemName"
  ],

  "rows": [

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-28",
      2331858,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-30",
      2414024,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-20",
      2339919,
      "28",
      "Nike Line Item 1"

    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-24",
      2405444,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-27",
      2339919,
      "28",
      "Nike Line Item 1"
    ],

    [

      "932",
      "Telephone_Creative_AU",
      "2016-08-25",
      2105121,
      "28",
      "Nike Line Item 1"
    ],

    [

      "932",
      "Telephone_Creative_AU",
      "2016-08-31",
      1137847,
      "28",
      "Nike Line Item 1"
    ],

    [

      "932",
      "Telephone_Creative_AU",
      "2016-08-29",
      2399983,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-26",
      2343039,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-22",
      2399983,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-23",
      2414284,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-21",
      2331858,
      "28",
      "Nike Line Item 1"
    ],

    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-19",
      2343039,
      "28",
      "Nike Line Item 1"
    ]

  ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Retrieving Eligible Forecast Data

Overview

This API enables you to retrieve Forecast data for all Ad Unit Ids for a particular account for a given time period. The API supports all possible dimensions, however no filtering can be applied as the endpoint provides forecast data for all Ad Unit Ids for a given account. The account Id for which data is requested is passed as an HTTP Request Header.

Request

           


Request Headers

                        

Header nameType ValueRequiredDescription
accountIdNumericExample: 34447YesAccount Id that has permission to get the Forecasting Report.
pubTokenString

${access_token}

Example: ae45ghj

Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.


For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                                                               

Parameter NameTypeValidationsDescriptions
fromDateString Date in  ISO 8601  format, as per dimensions preferred. Start date for fetching the data. Forecast API will not support forecasting for more than six months into the future.
toDateString Date in  ISO 8601  format, as per dimensions preferred. End date for fetching data.Forecast API will not support forecasting for more than six months into the future.
metricsStringComma-separated list of metrics specified in the supported metrics list.

A list of comma-separated metrics such as Total Impressions, Unique Users etc.

If metrics are not present in the query, we will provide you data against all available metrics.

dimensionsStringComma-separated list of dimensions specified in the supported dimensions list.

A list of comma-separated dimensions such as Pub ID, Site ID, etc. You can query with maximum 5 dimensions in single call.

If dimensions is not present in the query, we will provide you data against the date only.

sortStringComma-separated list of dimensions or metrics present in the query parameters.

A list of comma-separated dimensions / metrics keys indicating the sorting fields and sorting order.

If sort key not found in requested query either in dimension or metrics, you will get an Bad Request response along with error code INVALID_SORT_KEY.

filtersString Refer to the filter section in the document for the filter syntax and the supported filter operations.
pageNumberIntegerPage number to get data for a particular page.
Default value = 1.
Page number to get data for a particular page.
pageSizeIntegerNumber of records to fetch on a specific page number. If Page Size is not specified, the default value will be 100.

Indicates the number of records returned from the API on specific page.

Note: If Page Number and Page Size both are not mentioned in request then Page Number will be set as default value 1 and Page Size will be equal to Total Records.

adUnitIdsIntegerComma-separated list of Ad UnitI ds for a Line Item for which forecasting data is required.

Comma separated list of Ad Unit Ids for an existing Line Item or a line Item yet to be created.

If no Ad Unit Ids are passed, the corresponding request is considered for "Run of Networks."

Sample Request URL


Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/forecaster/forecast/eligible?fromDate=2016-08-30&toDate=2016-08-31&dimensions=adUnitId,date&metrics=totalImpressions,bookedPercentage,availablePercentage

Response

Response Fields

                  

Property NameValueDescription
columns[]ListComma separated name of the dimensions/metrics
rows[]ListEach row contains a lists of dimension values followed by the metric values. The order of dimensions and metrics is the same as specified in the request.


Sample Response JSON

    

Code Block
languagejs
linenumberstrue
{
  "metadata": {
    "pageNumber": 1,
    "pageSize": 2,
    "totalRecords": 2,
    "request": null
  },

  "columnHeaders": [
    "adUnitId",
    "adUnitName",
    "date",
    "totalImpressions",
    "bookedImpressions"

  ],

  "rows": [
    [
      "932",
      "Telephone_Creative_AU",
      "2016-08-30",
      2414284,
      2414024
    ],

    [

      "932",
      "Telephone_Creative_AU",
      "2016-08-31",
      2405444,
      2405444
    ]

  ]

}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Forecasting while creating a Line Item

Overview

This API 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. This endpoint will also provide information about competing line items when user set parameter competing LineItems=true.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
accountIdNumericExample: 34447YesAccount Id that has permission to get the Forecasting Report.
pubTokenString

${access_token}

Example: ae45ghj

Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.


For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters 

                                                     

Field NameTypeDescription
competingLineItemsBooleanThis field is used to show/hide competing line items in a Forecast result.
fromDateString Start date and time of an line item expected to start the delivering. Date Format in 'yyyy-MM-dd HH:mm:ss'  .
toDateString End date and time of an line item. Date Format in 'yyyy-MM-dd HH:mm:ss'  .
priorityInteger

Specifies the priority of a line item, relative to competing line items, in cases when inventory is over committed.

Supported Line Item Types and Priorities for Forecasting:

               

Line Item TypePriority Range
Sponsorship1-4
Standard5-8


goalInteger

Defines the total goal of the line item. For guaranteed line items goal  must  be achieved. For non-guaranteed, achieving goals are not guaranteed, however it is guaranteed to not exceed the goal.

Goal is closely tied to the Pricing model and UI must ensure that.

Example: If CPC pricing model is chosen goal is a whole number indicating number of clicks. If Share of Voice is chosen then goal is a whole number indicating percentage (1 - 100).

timeZoneIntegerTime Zone
sortStringThe column in the result set that needs sorting.
metricsString Array

A list of comma-separated metrics such as Total Impressions,Booked Impressions etc.

If metrics are not present in the query, we will provide you data against all available metrics.

targetingJsonTargeting associated with the Line Item. The structure is the same as represented in Preset Targeting APIs.

Sample Request URL

Code Block
languagejs
linenumberstrue
https://api.pubmatic.com/v1/forecaster/forecast/avails 


Sample Request JSON

Code Block
languagejs
linenumberstrue
{
    "competingLineItems": true,
    "fromDate": "2016-08-31 00:00:00",
    "toDate": "2016-08-31 23:59:00",
    "priority": 5,
    "goal": 1000,
    "timeZone": 15,
    "sort": "lineItemId",
    "metrics": ["bookedImpressions"],
    "targeting": {
        "os": {
            "targets": []
        },
        "geo": {
            "targets": []
        },
        "deviceType": {
            "targets": []
        },
        "device": {
            "targets": []
        },
        "deviceCapability": {
            "targets": []
        },
        "browser": {
            "targets": []
        },
        "browserLanguage": {
            "targets": []
        },
        "inventory": {
            "targets": [{
                "targetLevel": 2,
                "exclude": false,
                "targetValue": 932
            }]
        },
        "customKey": {
            "targets": []
        }
    },
    "accountId": 118385
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Response

Response Fields

                  

Property NameValueDescription
columns[]ListComma separated name of the dimensions/metrics
rows[]ListEach row contains a lists of dimension values followed by the metric values. The order of dimensions and metrics is the same as specified in the request.

Sample Response JSON

Code Block
languagejs
linenumberstrue
{
    "metadata": {
        "pageNumber": 1,
        "pageSize": 11,
        "totalRecords": 10,
        "request": null
    },
    "columnHeaders": [
        "priority",
        "lineItemId",
        "lineItemName",
        "lineItemType",
        "bookedImpressions"
    ],
    "rows": [
        [
            1,
            11,
            "Integration_Sanity_LineItem_3_Sp",
            "Sponsorship",
            394190
        ],
        [
            1,
            183,
            "PerfLineItem3_1",
            "Sponsorship",
            729096
        ],
        [
            6,
            1639,
            "Metadata test 2824 Sponsorship 1",
            "Open Exchange",
            122209
        ],
        [
            4,
            1760,
            "Contains only : and .",
            "Sponsorship",
            520
        ],
        [
            1,
            1852,
            "kartik multiformat",
            "Sponsorship",
            327625
        ],
        [
            1,
            2088,
            "LI ASAP",
            "Sponsorship",
            27042
        ],
        [
            1,
            2096,
            "asap",
            "Sponsorship",
            267040
        ],
        [
            1,
            2108,
            "Telephone_Creative_LineItem",
            "Sponsorship",
            35623
        ],
        [
            1,
            2139,
            "richmedia",
            "Sponsorship",
            28082
        ],
        [
            1,
            2189,
            "Native_custom_Lineitem_ios_RS_New",
            "Sponsorship",
            193715
        ]
    ],
    "totalAvailableImpressions": 0,
    "totalBookedImpressions": 2125142
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Supported Metrics

         

NameType Description
totalImpressionsNumericTotal forecasted Impressions
bookedImpressionsNumeric

Total booked impressions by already running Campaigns

bookedPercentageNumericBooked percentage out of total impressions
availableImpressionsNumericTotal available impressions excluding the booked ones
availablePercentageNumericAvailable percentage out of total impressions

Supported Dimensions

         

NameType Description
dateDateGrouped by Line Item start date and end date
hourNumeric

Grouped by Hour on each date

adSizeId
NumericGrouped by adSizeId
platformId
NumericGrouped by platformId
lineItemIdNumericLine Item Id is present by default
lineItemNameNumericLine Item Name is present by default
udidTypeIdNumericGrouped by udidTypeId
osIdNumericGrouped by osId
browserIdNumericGrouped by browserId
connectionTypeIdNumericGrouped by connectionTypeId
deviceTypeIdNumericGrouped by deviceTypeId
countryId
NumericGrouped by countryId
carrierIdNumericGrouped by carrierId
renderedBooleanWhether Ad was rendered or not
accountIdNumericAccount Id of Line Item
adUnitIdNumericAdUnits targeted by Line Item

Error Codes for Forecast API

The Forecaster API will display the following error codes apart from standard error code related to authentication and authorization.

                                                                                              

Field

Validations

Error Code

Http Status Code

Error Description

dimensions

Checks if dimension is supported by the API

INVALID_DIMENSION

400 - Bad Request

Requested dimensions not supported.

metrics

Checks if metric is supported by the API

INVALID_METRIC

400 - Bad Request

Requested metric not supported.

metrics

Check if metric count is in supported range

INVALID_METRIC_COUNT

400 - Bad Request

Metric count exceeds the supported count.

sort

Check if sort key present in dimension or metrics

INVALID_SORT_KEY

400 - Bad Request

Sort key can be either dimension or metrics passed in Query.

fromDate

Checks if fromDate is present in request

FROM_DATE_NOT_AVAILABLE

400 - Bad Request

From date is required.

toDate

Checks if toDate is present in request

TO_DATE_NOT_AVAILABLE

400 - Bad Request

To Date is required.

fromDate/

toDate

Checks if it is in valid format

INVALID_DATE_FORMAT

400 - Bad Request

Date format invalid.

filters

Checks if filter expression is parsed correctly

INVALID_FILTER

400 - Bad Request

Filter expression invalid. Not able to parse filter expression. Not able to parse filter expression.

filters

Check if filter is valid dimensions and metrics

INVALID_FILTER_KEY

400 - Bad Request

Invalid filter key(s). Filter can be applied only on valid dimensions and metrics.

filters

Check if filter expression is valid i.e. gt can not be applied on string data type

INVALID_FILTER_VALUE

400 - Bad Request

Data type mismatch in filter expression.

filters

Check if filter has 'OR' within dimensions or within metrics but not within dimensions &metrics.

INVALID_FILTER_COMBINATION

400 - Bad Request

Invalid filters combination applied, Filter can be applied only on dimension or metrics and not on both using || condition

Authentication

Checks if valid accountId or PubToken values are supplied while calling the API

PH_ACCESS_DENIED

401-

Unauthorized

Invalid accountId or Pub Token combination or the provided accountId does not have required permissions to Forecasting feature.

Sample Error Response

Code Block
languagejs
linenumberstrue
"errors": [
        {
            "errorCode": "INVALID_DATE_FORMAT",
            "error": "From date format invalid. Expected format: YYYY-MM-DD"
        },
        {
            "errorCode": "INVALID_NUMERIC_PARAMETER",
            "error": "Parameter value should be numeric.[pageSize]."
        }
    ],
[
{
         "errorCode": "PH_ACCESS_DENIED",
         "error": "Access Denied." 
  }
]‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍