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.

Target Type

Target Value

AD

An integer that identifies an ad ID. The bid multiplier determines the amount that the line may bid on ad placement opportunities that feature a specific ad.

To learn more, see Ads.

EXCHANGE

An integer that identifies a valid exchange ID. The bid multiplier determines the amount that the line may bid on ad placement opportunities made available through a specific exchange.

To learn more, see Exchanges.

DEAL

An integer that identifies a valid deal ID. The bid multiplier determines the amount that the line may bid on ad placement opportunities made available through a specific deal.

To learn more, see Deals.

AUCTION_TYPE

A string that identifies a valid deal ID. The bid multiplier determines the amount that the line may bid on ad placement opportunities made available through a specific auction type. Valid options include:

  • FirstPrice

  • SecondPrice

DAY_PARTING

An object that identifies day and hour day-parting values. The bid multiplier determines the amount that the line may bid on ad placement opportunities on certain days of the week or hours of the day.

  • day - A string that specifies the day targeted. Valid values: [MON, TUE, WED, THU, FRI, SAT, SUN].

  • hour - An integer that specifies the hours of the day targeted. Valid values: [0-23].

To learn more, see Day Parting Targeting.

SEGMENT

An integer that specifies an audience ID. The bid multiplier determines the amount that the line may bid on ad placement opportunities served to a specific audience or segment.

To learn more, see Segment Targeting.

AD_POSITION

A string that specifies the ad position. The bid multiplier determines the amount that the line may bid on ad placement opportunities in a specific ad position.

The AD_POSITION targeting type is only valid for lines serving display ads.

Valid options include:

  • ABOVE_FOLD

  • PARTIAL_VIEW

  • BELOW_FOLD

  • UNKNOWN

To learn more, see Ad Position Targeting.

DOMAIN

A string that specifies a site list domain. The bid multiplier determines the amount that the line may bid on ad placement opportunities served from a specific domain.

  • targetValue should be set to null. Specify the desired app name or web site name using targetDomain.

  • isAppName should be set to either true or false depending on the type of the value in targetDomain.

To learn more, see App & Site Lists.

DEVICE

A string that specifies a device. The bid multiplier determines the amount that the line may bid on ad placement opportunities served to a specific device type.

Valid options include:

  • Desktop

  • Phone

  • Tablet

  • ConnectedTv

  • Unknown

To learn more, see Technology Targeting.

WEATHER_CONDITION

A string that specifies a weather condition. The bid multiplier determines the amount that the line may bid on ad placement opportunities served from a specific weather condition.

Valid options include:

  • SNOWY

  • RAINY

  • WINDY

  • CLOUDY

  • SUNNY

  • STORMY

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, see /traffic/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, see /traffic/lines.

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

Max CPM Price

Bid Multiplier

BM Bid Price

$5.00

0.05

$0.25

$5.00

2.00

$10.00

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.

Field

Description

Data Type

id

A read-only field that specifies the bid multiplier ID.

integer

lineId

Specifies the line ID.

integer

targetType

Specifies the bid multiplier’s targeting attribute. Valid values include:

  • AD

  • EXCHANGE

  • DEAL

  • AUCTION_TYPE

  • DAY_PARTING

  • SEGMENT

  • AD_POSITION

  • DOMAIN

  • DEVICE

  • WEATHER_CONDITION

To learn more, see Targeting Types and Values.

string

targetValue

Specifies a value that is determined by the targetType.

  • If AD, EXCHANGE, DEAL or SEGMENT: an number that represents the id of the targetType`. For example, a specific ad ID, exchange ID, deal ID or audience ID. To learn more, see Targeting Types and Values.

  • If AD_POSITION, DEVICE, AUCTION_TYPE or WEATHER_CONDITION: a string that represents a text value. To learn more, see Targeting Types and Values.

  • If DAY_PARTING: an object that represents the day and hour. To learn more, see Day Parting Object.

number/ string / object

targetDomain

A string that specifies a site list domain. Only used by targetType DOMAIN

string

isAppName

Specifies the type of targetDomain value when targetType is DOMAIN.

  • true: if targetDomain is a mobile app.

  • false: if targetDomain is a web site.

boolean

multiplier

Specifies the bid multiplier value (a number between 0 and 9.95), which is used to calculate the amount the line will bid on ad placement opportunites that match the specified targeting attributes.

Depending on the value specified, the line may bid higher or lower than the line’s Max CPM Price for particular ad placements. To learn more, see Bid Multiplier Bid Price Calculation.

number

Multiplier Cap

The multiplierCap resource is defined by the following fields:

Field

Description

Data Type

multiplierCap

Specifies the maximum amount that a line may bid on ad placement opportunites that satisfy the targeting attributes specified for two or more bid multipliers. To learn more, see Maximum Multiplied CPM Bid Caps.

number

Read Bid Multipliers

Returns the bid multipliers associated with the specified line.

GET /traffic/lines/{lineId}/bidmultipliers

Parameters

Parameter

Parameter Type

Description

Data Type

Required

lineId

path

Specifies the line ID.

integer

Y

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
      }
    ],
    "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.

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.

Parameter

Parameter Type

Description

Data Type

Required

lineId

path

Specifies the line ID number.

integer

Y

added

body

Specifies an array of bidMultipler objects.

array

N

edited

body

Specifies an array of objects. Each object consists of a key-value pair that identifies the bid multipler by its id number and updated values for the specified bidMulitiplier fields.

array

N

removed

body

Specifies an array of bid mulipliers identified by their id numbers.

array

N

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
    }
  ]
}

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
    }
  ],
  "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, see Maximum Multiplied CPM Bid Caps.

Parameters

Parameter

Parameter Type

Description

Data Type

Required

lineId

path

Specifies the line ID.

integer

Y

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

Status Code

Description

200

The request has succeeded.

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, see Maximum Multiplied CPM Bid Caps.

Parameters

Parameter

Parameter Type

Description

Data Type

Required

lineId

path

Specifies the line ID.

integer

Y

multiplierCap

body

Specifies the line’s bid multiplier cap, the maximum amount the line can bid on any ad placement opportunity.

number

Y

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

Status Code

Description

201

The request has been fulfilled and has resulted in one or more new resources being created.

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, see 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.

Parameter

Parameter Type

Description

Data Type

Required

lineId

path

Specifies the line ID.

integer

Y

multiplierCap

body

Specifies the line’s Multiplier Cap, the maximum amount the line can bid on any ad placement opportunity.

number

Y

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

Status Code

Description

204

The server has successfully fulfilled the request and that there is no additional content to send in the response payload body.