Listing Campaign Performance Forecasts

curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dailyBudget": 123,
  "dateRange": {
    "startDate": "2023-12-25",
    "endDate": "2023-12-25"
  },
  "targetRoas": 123,
  "campaignFormat": "listing",
  "campaignType": "autobidding",
  "products": [
    {
      "id": "<string>"
    }
  ],
  "triggers": [
    {
      "value": "<string>"
    }
  ],
  "targets": [],
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  },
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "user_segment",
        "segmentId": "<string>",
        "multiplier": 0.5
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  }
}
'

import requests

url = "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing"

payload = {
    "dailyBudget": 123,
    "dateRange": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25"
    },
    "targetRoas": 123,
    "campaignFormat": "listing",
    "campaignType": "autobidding",
    "products": [{ "id": "<string>" }],
    "triggers": [{ "value": "<string>" }],
    "targets": [],
    "targetingFilters": {
        "isActive": True,
        "targetingFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    },
    "multiplierConfig": {
        "isActive": True,
        "multipliers": [
            {
                "type": "user_segment",
                "segmentId": "<string>",
                "multiplier": 0.5
            }
        ]
    },
    "exclusionFilters": {
        "isActive": True,
        "exclusionFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dailyBudget: 123,
    dateRange: {startDate: '2023-12-25', endDate: '2023-12-25'},
    targetRoas: 123,
    campaignFormat: 'listing',
    campaignType: 'autobidding',
    products: [{id: '<string>'}],
    triggers: [{value: '<string>'}],
    targets: [],
    targetingFilters: {
      isActive: true,
      targetingFilters: [{type: 'user_segment', segmentId: '<string>'}]
    },
    multiplierConfig: {
      isActive: true,
      multipliers: [{type: 'user_segment', segmentId: '<string>', multiplier: 0.5}]
    },
    exclusionFilters: {
      isActive: true,
      exclusionFilters: [{type: 'user_segment', segmentId: '<string>'}]
    }
  })
};

fetch('https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dailyBudget' => 123,
    'dateRange' => [
        'startDate' => '2023-12-25',
        'endDate' => '2023-12-25'
    ],
    'targetRoas' => 123,
    'campaignFormat' => 'listing',
    'campaignType' => 'autobidding',
    'products' => [
        [
                'id' => '<string>'
        ]
    ],
    'triggers' => [
        [
                'value' => '<string>'
        ]
    ],
    'targets' => [
        
    ],
    'targetingFilters' => [
        'isActive' => true,
        'targetingFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ],
    'multiplierConfig' => [
        'isActive' => true,
        'multipliers' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>',
                                'multiplier' => 0.5
                ]
        ]
    ],
    'exclusionFilters' => [
        'isActive' => true,
        'exclusionFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing"

	payload := strings.NewReader("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"campaignFormat\": \"listing\",\n  \"campaignType\": \"autobidding\",\n  \"products\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"campaignFormat\": \"listing\",\n  \"campaignType\": \"autobidding\",\n  \"products\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"campaignFormat\": \"listing\",\n  \"campaignType\": \"autobidding\",\n  \"products\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "forecasts": {
    "impressions": {
      "forecastValue": 150000,
      "forecastIntervalMin": 142000,
      "forecastIntervalMax": 158000
    },
    "clicks": {
      "forecastValue": 12500,
      "forecastIntervalMin": 11800,
      "forecastIntervalMax": 13200
    },
    "purchases": {
      "forecastValue": 875,
      "forecastIntervalMin": 820,
      "forecastIntervalMax": 930
    },
    "sales": {
      "forecastValue": 52500,
      "forecastIntervalMin": 49000,
      "forecastIntervalMax": 56000
    },
    "adSpend": {
      "forecastValue": 10500,
      "forecastIntervalMin": 10000,
      "forecastIntervalMax": 11000
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Forecasting Service

Listing Campaign Performance Forecasts

Get performance forecasts with confidence intervals for listing campaigns.

Campaign types:

autobidding: provide products (at least one product id).
manual: provide bids (each with productId and bidAmount > 0).

Returns total campaign forecasts (not daily) for:

Total impressions, clicks, purchases, sales, and ad spend with confidence intervals.

Constraints:

Date range cannot exceed 31 days.

POST

public

toptimize

forecasting

campaigns

listing

Listing Campaign Performance Forecasts

curl --request POST \
  --url https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dailyBudget": 123,
  "dateRange": {
    "startDate": "2023-12-25",
    "endDate": "2023-12-25"
  },
  "targetRoas": 123,
  "campaignFormat": "listing",
  "campaignType": "autobidding",
  "products": [
    {
      "id": "<string>"
    }
  ],
  "triggers": [
    {
      "value": "<string>"
    }
  ],
  "targets": [],
  "targetingFilters": {
    "isActive": true,
    "targetingFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  },
  "multiplierConfig": {
    "isActive": true,
    "multipliers": [
      {
        "type": "user_segment",
        "segmentId": "<string>",
        "multiplier": 0.5
      }
    ]
  },
  "exclusionFilters": {
    "isActive": true,
    "exclusionFilters": [
      {
        "type": "user_segment",
        "segmentId": "<string>"
      }
    ]
  }
}
'

import requests

url = "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing"

payload = {
    "dailyBudget": 123,
    "dateRange": {
        "startDate": "2023-12-25",
        "endDate": "2023-12-25"
    },
    "targetRoas": 123,
    "campaignFormat": "listing",
    "campaignType": "autobidding",
    "products": [{ "id": "<string>" }],
    "triggers": [{ "value": "<string>" }],
    "targets": [],
    "targetingFilters": {
        "isActive": True,
        "targetingFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    },
    "multiplierConfig": {
        "isActive": True,
        "multipliers": [
            {
                "type": "user_segment",
                "segmentId": "<string>",
                "multiplier": 0.5
            }
        ]
    },
    "exclusionFilters": {
        "isActive": True,
        "exclusionFilters": [
            {
                "type": "user_segment",
                "segmentId": "<string>"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dailyBudget: 123,
    dateRange: {startDate: '2023-12-25', endDate: '2023-12-25'},
    targetRoas: 123,
    campaignFormat: 'listing',
    campaignType: 'autobidding',
    products: [{id: '<string>'}],
    triggers: [{value: '<string>'}],
    targets: [],
    targetingFilters: {
      isActive: true,
      targetingFilters: [{type: 'user_segment', segmentId: '<string>'}]
    },
    multiplierConfig: {
      isActive: true,
      multipliers: [{type: 'user_segment', segmentId: '<string>', multiplier: 0.5}]
    },
    exclusionFilters: {
      isActive: true,
      exclusionFilters: [{type: 'user_segment', segmentId: '<string>'}]
    }
  })
};

fetch('https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dailyBudget' => 123,
    'dateRange' => [
        'startDate' => '2023-12-25',
        'endDate' => '2023-12-25'
    ],
    'targetRoas' => 123,
    'campaignFormat' => 'listing',
    'campaignType' => 'autobidding',
    'products' => [
        [
                'id' => '<string>'
        ]
    ],
    'triggers' => [
        [
                'value' => '<string>'
        ]
    ],
    'targets' => [
        
    ],
    'targetingFilters' => [
        'isActive' => true,
        'targetingFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ],
    'multiplierConfig' => [
        'isActive' => true,
        'multipliers' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>',
                                'multiplier' => 0.5
                ]
        ]
    ],
    'exclusionFilters' => [
        'isActive' => true,
        'exclusionFilters' => [
                [
                                'type' => 'user_segment',
                                'segmentId' => '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing"

	payload := strings.NewReader("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"campaignFormat\": \"listing\",\n  \"campaignType\": \"autobidding\",\n  \"products\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"campaignFormat\": \"listing\",\n  \"campaignType\": \"autobidding\",\n  \"products\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/public/v1/toptimize/forecasting/campaigns/listing")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dailyBudget\": 123,\n  \"dateRange\": {\n    \"startDate\": \"2023-12-25\",\n    \"endDate\": \"2023-12-25\"\n  },\n  \"targetRoas\": 123,\n  \"campaignFormat\": \"listing\",\n  \"campaignType\": \"autobidding\",\n  \"products\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"triggers\": [\n    {\n      \"value\": \"<string>\"\n    }\n  ],\n  \"targets\": [],\n  \"targetingFilters\": {\n    \"isActive\": true,\n    \"targetingFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  },\n  \"multiplierConfig\": {\n    \"isActive\": true,\n    \"multipliers\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\",\n        \"multiplier\": 0.5\n      }\n    ]\n  },\n  \"exclusionFilters\": {\n    \"isActive\": true,\n    \"exclusionFilters\": [\n      {\n        \"type\": \"user_segment\",\n        \"segmentId\": \"<string>\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "forecasts": {
    "impressions": {
      "forecastValue": 150000,
      "forecastIntervalMin": 142000,
      "forecastIntervalMax": 158000
    },
    "clicks": {
      "forecastValue": 12500,
      "forecastIntervalMin": 11800,
      "forecastIntervalMax": 13200
    },
    "purchases": {
      "forecastValue": 875,
      "forecastIntervalMin": 820,
      "forecastIntervalMax": 930
    },
    "sales": {
      "forecastValue": 52500,
      "forecastIntervalMin": 49000,
      "forecastIntervalMax": 56000
    },
    "adSpend": {
      "forecastValue": 10500,
      "forecastIntervalMin": 10000,
      "forecastIntervalMax": 11000
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Autorisations

Authorization

string

header

requis

A valid API key generated in Topsort's UI. Use the TSE API key if calling auctions or events API, otherwise use the TSC API key.

Corps

application/json

PublicAutobiddingListingCampaignForecastRequest
PublicManualListingCampaignForecastRequest

dailyBudget

number

requis

Daily budget for the campaign

dateRange

PublicDateRange · object

requis

Campaign date range

Show child attributes

targetRoas

number

requis

Target Return on Ad Spend

campaignFormat

string

requis

Campaign format type. Must be 'listing'.

Allowed value: "listing"

campaignType

string

requis

Campaign type. Must be 'autobidding'.

Allowed value: "autobidding"

products

PublicProductRequest · object[]

requis

List of products in the campaign (required)

Minimum array length: 1

Show child attributes

triggers

PublicTriggerRequest · object[]

List of campaign triggers (optional, defaults to empty list)

Show child attributes

targets

enum<string>[] | null

Optional list of target variables to forecast. If not provided, all targets will be forecasted.

Options disponibles:

ad_spend,

clicks,

impressions,

purchases,

sales

targetingFilters

PublicCampaignTargetingFilters · object | null

Optional audience targeting, in the same shape as campaign creation. When active, the forecast covers only users in these segments. Segment IDs are the marketplace's external segment IDs.

Show child attributes

multiplierConfig

PublicCampaignMultiplierConfig · object | null

Optional audience bid multipliers, in the same shape as campaign creation. Segment IDs are the marketplace's external segment IDs.

Show child attributes

exclusionFilters

PublicCampaignExclusionFilters · object | null

Optional audience exclusion, in the same shape as campaign creation. When active, the forecast leaves out users in these segments. Segment IDs are the marketplace's external segment IDs.

Show child attributes

Réponse

Successful Response

forecasts

PublicCampaignForecastMetrics · object

requis

Campaign performance forecasts

Show child attributes

Général

Exemples d'enchères

Exemples de webhooks

Auctions

Events

Toptimize

Toppie API

Campaign API

Catalog API

Billing API

Reporting API

Invitation API

User API

Webhooks API

Assets API

Segments Service

Offsite Ads API

Forecasting Service

Media API

Placement API

Export API

API Reference

Listing Campaign Performance Forecasts

Autorisations

Corps

Réponse