Eligibility Forecast

To forecast a new ad ignoring the ads that are already running in your network, you can use an eligible forecast. For an eligible forecast, you must supply an ad together with the end date and forecast type. The following is an example of an eligible forecast with an ad with no particular targeting criteria:

{
  "Type": "eligible",
  "EndDate": "2023-03-20",
  "Ad": {
    "Id": 1,
    "Flight": {
      "Id": 1,
      "GoalType": 1,
      "GoalAmount": 10000,
      "NetworkId": 12345,
      "PriorityId": 1,
      "StartDate": "2023-03-13T00:00:00",
      "Priority": {
        "Id": 1,
        "Order": 5,
        "Type": "lottery"
      }
    },
    "Creative": {
      "Id": 1,
      "AdType": 1
    }
  },
  "Params": {
    "Sampling": 3
  }
}

The above forecast request should produce a result like the following:

{
  "resultStatus": "success",
  "result": {
    "total": {
      "impressions": 9772192,
      "uniqueUsers": 2665288
    }
  },
  "id": "86439249-4544-4ade-b48c-015a0ecede25",
  "status": "finished",
  "progress": 100.0,
  "desc": "Forecast is finished"
}

We understand a lot of the fields in the above payload are unnecessary. You shouldn’t need to set up IDs for entities that you’re planning. We’re working on improving the API to be more aligned with what you need to set up in the management API. For the time being, you need to define a flight id, network id, advertiser id and priority id, even though in most of the cases they’re not going to be used in a meaningful way.

With the above in place, we can start exploring our inventory and narrowing our ad. For example, we can run the same request but grouped by $site:

{
  "Type": "eligible",
  "EndDate": "2023-03-20",
  "Ad": {
    "Id": 1,
    "Flight": {
      "Id": 1,
      "GoalType": 1,
      "GoalAmount": 10000,
      "NetworkId": 11030,
      "AdvertiserId": 1,
      "PriorityId": 1,
      "StartDate": "2023-03-13T00:00:00",
      "Priority": {
        "Id": 1,
        "Order": 5,
        "Type": "lottery"
      }
    },
    "Creative": {
      "Id": 1,
      "AdType": 1
    }
  },
  "Params": {
    "Sampling": 3,
    "GroupBy": ["$site"]
  }
}

This should result in a list of impressions and unique users eligible per site:

{
  "resultStatus": "success",
  "result": {
    "total": {
      "impressions": 9772192,
      "uniqueUsers": 2665288
    },
    "grouped": [
      {
        "key": {
          "$site": 1234567
        },
        "value": {
          "impressions": 6976,
          "uniqueUsers": 1456
        }
      },
      {
        "key": {
          "$site": 1234568
        },
        "value": {
          "impressions": 221696,
          "uniqueUsers": 92184
        }
      },
      {
        "key": {
          "$site": 1234569
        },
        "value": {
          "impressions": 7192,
          "uniqueUsers": 2456
        }
      },
      (...)
  },
  "id": "5cd77b8e-4271-4f68-8914-f23104cfd907",
  "status": "finished",
  "progress": 100.0,
  "desc": "Forecast is finished"
}

We can narrow our ad definition to only target decision requests of a particular site:

{
  "Type": "eligible",
  "EndDate": "2023-03-20",
  "Ad": {
    "Id": 1,
    "Flight": {
      "Id": 1,
      "GoalType": 1,
      "GoalAmount": 10000,
      "NetworkId": 12345,
      "AdvertiserId": 1,
      "PriorityId": 1,
      "StartDate": "2023-03-13T00:00:00",
      "Priority": {
        "Id": 1,
        "Order": 5,
        "Type": "lottery"
      },
      "SiteZoneTargeting": {
        "Include": [
          {
            "SiteId": 1234569
          }
        ]
      }
    },
    "Creative": {
      "Id": 1,
      "AdType": 1
    }
  },
  "Params": {
    "Sampling": 3
  }
}

We can also narrow down the ad definition to only target specific keywords:

{
  "Type": "eligible",
  "EndDate": "2023-03-20",
  "Ad": {
    "Id": 1,
    "Flight": {
      "Id": 1,
      "GoalType": 1,
      "GoalAmount": 10000,
      "NetworkId": 12345,
      "AdvertiserId": 1,
      "PriorityId": 1,
      "StartDate": "2023-03-13T00:00:00",
      "Priority": {
        "Id": 1,
        "Order": 5,
        "Type": "lottery"
      },
      "SiteZoneTargeting": {
        "Include": [
          {
            "SiteId": 1234569
          }
        ]
      },
      "KeywordTargeting": {
        "Include": [
          [
            "keyword1"
          ],
          [
            "keyword2"
          ]
        ]
      }
    },
    "Creative": {
      "Id": 1,
      "AdType": 1
    }
  },
  "Params": {
    "Sampling": 3
  }
}

And to include custom targeting and creative templates to be used in AdQuery filters, grouping results by the local date of each request:

{
  "Type": "eligible",
  "EndDate": "2023-03-20",
  "Ad": {
    "Id": 1,
    "Flight": {
      "Id": 1,
      "GoalType": 1,
      "GoalAmount": 10000,
      "NetworkId": 12345,
      "AdvertiserId": 1,
      "PriorityId": 1,
      "StartDate": "2023-03-13T00:00:00",
      "Priority": {
        "Id": 1,
        "Order": 5,
        "Type": "lottery"
      },
      "SiteZoneTargeting": {
        "Include": [
          {
            "SiteId": 1234569
          }
        ]
      },
      "KeywordTargeting": {
        "Include": [
          [
            "keyword1"
          ],
          [
            "keyword2"
          ]
        ]
      },
      "CustomTargeting": "[\"custom_page_name\"] contains homepage"
    },
    "Creative": {
      "Id": 1,
      "AdType": 1, 
      "QueryableFields": {
        "ctSize": {
          "type": "String",
          "value": "large"
        },
        "ctPrice": {
          "type": "Number",
          "value": 42
        }
      }
    }
  },
  "Params": {
    "Sampling": 3,
    "GroupBy": ["$datetime.date"]
  }
}

The above forecast request should produce results in a schema similar to the following:

{
  "resultStatus": "success",
  "result": {
    "total": {
      "impressions": 10504,
      "uniqueUsers": 3568
    },
    "grouped": [
      {
        "key": {
          "$datetime.date": "2023-03-19"
        },
        "value": {
          "impressions": 1496,
          "uniqueUsers": 672
        }
      },
      {
        "key": {
          "$datetime.date": "2023-03-20"
        },
        "value": {
          "impressions": 1416,
          "uniqueUsers": 624
        }
      },
      {
        "key": {
          "$datetime.date": "2023-03-15"
        },
        "value": {
          "impressions": 1400,
          "uniqueUsers": 600
        }
      },
      {
        "key": {
          "$datetime.date": "2023-03-14"
        },
        "value": {
          "impressions": 1176,
          "uniqueUsers": 632
        }
      },
      {
        "key": {
          "$datetime.date": "2023-03-17"
        },
        "value": {
          "impressions": 1736,
          "uniqueUsers": 744
        }
      },
      {
        "key": {
          "$datetime.date": "2023-03-18"
        },
        "value": {
          "impressions": 1704,
          "uniqueUsers": 768
        }
      },
      {
        "key": {
          "$datetime.date": "2023-03-16"
        },
        "value": {
          "impressions": 1576,
          "uniqueUsers": 680
        }
      }
    ]
  },
  "id": "98e2af73-8d23-40fd-a760-d5741ac94d41",
  "status": "finished",
  "progress": 100.0,
  "desc": "Forecast is finished"
}

Eligibility forecasts are the quickest to complete since they don’t take into account existing ads.