Bid Multipliers

This article describes services for reading, adding, and updating bid multipliers.

Overview

A bid multiplier is a targeting-specific configuration that specifies the relative weight that should be given to targeted ad placement opportunities.

For example, an ad served to a mobile phone may be more valuable to you than a comparable desktop impression and you may be willing to bid more for those ad placements. Bid multipliers enable you to specify multiplier values that affect the amount a line may bid for targeted opportunities.

Depending on the multiplier specified (a value between 0 and 9.95), the line may bid more or less than its Max CPM Price (bidPrice) on an ad placement opportunity with a set of target attributes.

Targeting Types and Values

Bid multipliers enable you to bid on ad placements at different rates depending on the targeting attributes identified in those opportunities.

The targeting attribute is identified by a targetType and a targetValue.

Bid multipliers are supported for the targeting types specified in the table below. For each targeting attribute, a different bid multiplier value (multiplier) may be specified.

Note

The bid multiplier applies only to those targeting attributes that are applied to a line. If no targeting attribute is defined for the line, the line’s bid multiplier for that attribute is ignored.

To learn more, refer to About Targeting.

Bid Multiplier Bid Price Calculation

Depending on the bid multiplier’s multiplier value, a line may bid higher or lower than its Max CPM Price (bidPrice) on ad placement opportunities.

With bid multipliers, the amount that a line can bid (its BM Bid Price) for an ad placement is calculated automatically using the formula:

BM Bid Price = Bid Multiplier * Max CPM Price

Where the Bid Multiplier is the multiplier value specified for the bid multiplier and the Max CPM Price is the bidPrice value specified for the line.

Note

A line’s Max CPM Price specifies the maximum amount that you are willing to pay per thousand impressions. To learn more, refer to Lines.

For example, say that you have specified a bidPrice of $5 for one of your lines. Depending on the specified bid multiplier value, you may bid more or less than the line’s bidPrice for a targeted ad placement.

Maximum Multiplied CPM Bid Caps

If an ad placement opportunity satisfies the targeting attributes of two or more bid multipliers, the line’s BM Bid Price–the amount the line will bid on that opportunity–is constrained by the line’s multiplierCap value.

The platform compares the line’s multiplierCap value with the product of all bid multiplier multiplier values (BMn) and bids the lower of the two:

BM Bid Price = Min[(Max CPM Price BM1 BM2 * … BMn), (Multiplier Cap)]

If no multiplierCap value is specified, the line bids the product of its bid multipliers.

Endpoint

You can use this endpoint to read, create, and update bid multiplier objects.

/traffic/lines/{lineId}/bidmultipliers

A bid multiplier is always line-specific. You must specify the lineId a line whenever you read, create, or update a bid multiplier object. The action taken depends on the HTTP method and the parameters specified.

• Use the GET method to read existing bid multipliers.

• Use the POST method to add new bid multipliers.

• Use the PUT method to update bid multipliers.

You can also specify a bid multiplier cap using a distinct endpoint:

/traffic/lines/{lineId}/bidmultipliercap

A maximum multiplied CPM value is always line-specific. The action taken depends on the HTTP method and the parameters specified.

• Use the GET method to read the maximum multiplied CPM.

• Use the POST method to add new maximum multiplied CPMs.

• Use the PUT method to update maximum multiplied CPMs.

Resources

Two resources: a bid multiplier object and the line’s max multiplied CPM resource.

Bid Multiplier

The bidMultiplier resource is defined by the following fields.

Multiplier Cap

The multiplierCap resource is defined by the following fields:

Read Bid Multipliers

Returns the bid multipliers associated with the specified line.

GET /traffic/lines/{lineId}/bidmultipliers

Parameters

Example Request

GET /traffic/lines/390951/bidmultipliers

Example Response

{
  "response": {
    "bidMultipliers": [
      {
        "id": 1600,
        "targetType": "AD",
        "targetValue": 454600,
        "multiplier": 1.8
      },
      {
        "id": 2220,
        "targetType": "EXCHANGE",
        "targetValue": 17,
        "multiplier": 2.65
      },
      {
        "id": 2221,
        "targetType": "DAY_PARTING",
        "targetValue": {
          "day": "SAT",
          "hour": 11
        },
        "multiplier": 3.25
      },
      {
        "id": 2222,
        "targetType": "AD_POSITION",
        "targetValue": "ABOVE_FOLD",
        "multiplier": 0.8
      },
      {
        "id": 2223,
        "targetType": "DEVICE",
        "targetValue": "Desktop",
        "multiplier": 0.85
      },
      {
        "id": 2224,
        "targetType": "WEATHER_CONDITION",
        "targetValue": "WINDY",
        "multiplier": 0.85
      },
      {
        "id": 2315,
        "targetType": "EXCHANGE",
        "targetValue": 1,
        "multiplier": 2.65
      },
      {
        "id": 2556,
        "targetType": "DOMAIN",
        "targetDomain": "yahoo.com",
        "multiplier": 2.65,
        "isAppName": true
      },
      {
        "id": 2557,
        "targetType": "DOMAIN",
        "targetDomain": "sports.yahoo.com",
        "multiplier": 2.65,
        "isAppName": false
      },
      {
        "id": 150987,
        "targetType": "SUPPLY_GROUP",
        "targetValue": 1,
        "multiplier": 2.0,
        "name": "GROUP 1A (1.0 - 9.0)"
      },
      {
        "id": 151024,
        "targetType": "SITE_X_DEVICE",
        "targetValue": 499,
        "multiplier": 1.0,
        "name": "Newsweek - Mobile"
      },
      {
        "id": 151014,
        "targetType": "SITE_GROUP_X_DEVICE",
        "targetValue": 501,
        "multiplier": 1.0,
        "name": "Fox News - Desktop"
      },
    ],
    "bidMultiplierCap": {
      "id": 1375,
      "lineId": 412063,
      "multiplierCap": 5.1,
      "bmAdLearnOverride": false
    }
  },
  "errors": null,
  "timeStamp": "2020-03-02T19:44:53.414Z"
}

Create / Update / Delete Bid Multipliers

Creates, updates or deletes bidMultiplier objects for the specified line.

Note

After adding a bid multiplier, multiplier is the only field that can be edited and updated.

POST /traffic/lines/{lineId}/bidmultipliers

The POST method enables you to add, edit, or delete multiple bidMultiplier objects in a single request.

Parameters

The lineId parameter is specified in the url path. All other fields are specified in the body of the application/json payload.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/412063/bidmultipliers

Example Request Body

{
  "added": [
    {
      "targetType": "DOMAIN",
      "targetDomain": "finance.yahoo.com",
      "multiplier": 1.45,
      "isAppName": false
    },
    {
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "SUN",
        "hour": 14
      },
      "multiplier": 0.5
    }
  ],
  "removed": [
    521
  ],
  "edited": [
    {
      "id": 528,
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "WED",
        "hour": 12
      },
      "multiplier": 2
    },
    {
      "id": 529,
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "THU",
        "hour": 1
      },
      "multiplier": 1.2
    }
  ],
  "removedItems": [
    {
      "id": 575,
      "targetType": "SITE_X_DEVICE",
      "targetValue": 266,
      "multiplier": 1.2
    },
    {
      "id": 580,
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "SUN",
        "hour": 12
      },
      "multiplier": 0.5
    }
  ]
}

Example Response

{
  "response": [
    {
      "id": 2684,
      "targetType": "DOMAIN",
      "targetDomain": "finance.yahoo.com",
      "multiplier": 1.45,
      "isAppName": false
    },
    {
      "id": 528,
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "WED",
        "hour": 12
      },
      "multiplier": 2
    },
    {
      "id": 529,
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "THU",
        "hour": 1
      },
      "multiplier": 1.2
    },
    {
      "id": 531,
      "targetType": "DAY_PARTING",
      "targetValue": {
        "day": "SUN",
        "hour": 14
      },
      "multiplier": 0.5
    }
  ],
  "bidMultiplierCap": null
  "errors": null,
  "timeStamp": "2019-11-27T00:50:13.769Z"
}

Read Multiplier Cap

Reads the multiplierCap value of the specified line.

GET /traffic/lines/{lineId}/bidmultipliercap

The multiplierCap specifies the maximum amount that a line can bid on ad placement opportunities that match the targeting attributes of two or more bid multipliers. To learn more, refer to Maximum Multiplied CPM Bid Caps.

Parameters

Example Request

https://dspapi.admanagerplus.yahoo.com/traffic/lines/365771/bidmultipliercap

Example Response

{
  "response": {
    "multiplierCap": 2
  },
  "errors": null,
  "timeStamp": "2018-03-01T21:17:35Z"
}

Status and Error Codes

Create Multiplier Cap

Specifies the multiplierCap value for the specified line.

POST /traffic/lines/{lineId}/bidmultipliercap

The multiplierCap specifies the maximum amount that a line can bid on ad placement opportunities that match the targeting attributes of two or more bid multipliers. To learn more, refer to Maximum Multiplied CPM Bid Caps.

Parameters

Example Request

The lineId is specified in the path of the endpoint.

https://dspapi.admanagerplus.yahoo.com/traffic/lines/365771/bidmultipliercap

The multiplierCap parameter is specified in the body of the application/json payload.

{
   "multiplierCap":"1"
}

Status and Error Codes

Update Multiplier Cap

Updates the multiplierCap value for the specified line.

PUT /traffic/lines/{lineId}/bidmultipliercap

The multiplierCap specifies the maximum amount that a line can bid on ad placement opportunities that match the targeting attributes of two or more bid multipliers. To learn more, refer to Maximum Multiplied CPM Bid Caps.

Parameters

The API takes two parameters: a lineID in the path of the URL endpoint and the updated multiplierCap value, which is specified in the body of the application/json payload.

Example Request

The lineId is specified in the path of the endpoint.

https://dspapi.admanagerplus.yahoo.com/traffic/lines/365771/bidmultipliercap

The multiplierCap parameter is specified in the body of the application/json payload.

{
  "multiplierCap":"2"
}

Status and Error Codes