Forecasting while creating a Line Item

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Jun 14, 2017
Version 4Show Document
  • View in full screen mode

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 competingLineItems=true.

Request

           

URIHTTP Method
http://$URI_PREFIX/{apiVersion}/forecaster/forecast/avails POST

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.
fromDateStringStart date and time of an line item expected to start the delivering. Date Format in 'yyyy-MM-dd HH:mm:ss' .
toDateStringEnd 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

http://$URI_PREFIX/{apiVersion}/forecaster/forecast/avails 

Sample Request JSON

    


{
    "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

    


{
    "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
}

Response Codes

HTTP Status Codes

Error Codes for Forecast API

Attachments

    Outcomes