Bid Multipliers

This article describes services for reading, adding, and updating 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 following the following targeting types: ads, exchanges, day parting, domains, devices, ad position, and audiences. For each targeting attribute, a different bid multiplier value (multiplier) may be specified.

Bid multiplier can currently be set on the following target types:

Table 71 Bid Multiplier Target Type
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.

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.

To learn more, see Day Parting Object.

AUDIENCE 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.
AD_POSITION

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 /traffic/targeting/index.

APP_SITE

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

To learn more, see /traffic/sitelists.

DEVICE

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
  • UNKNOWN

To learn more, see /traffic/targeting/index.

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.

Note

The Oath Ad Platforms DSP API does not support bid multipliers for pixel, demographic, or site list targeting.

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.

Endpoints

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

/traffic/lines/{lineId}/bidmultiplier

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.

Table 72 Bid Multiplier Field
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
  • DAY_PARTING
  • AUDIENCE
  • AD_POSITION
  • APP_SITE
  • DEVICE

To learn more, see Targeting Types and Values.

string
targetValue

Specifies a targetType-specific target value that identifies a targeting attribute.

  • If AD, EXCHANGE, AUDIENCE, or APP_SITE, an integer that identifies a particular targeting attribute. For example, a specific ad ID, exchange ID, or audience ID. To learn more, see Targeting Types and Values.
  • If AD_POSITION or DEVICE, an enum that identifies a particular targeting attribute. To learn more, see Targeting Types and Values.
  • If DAY_PARTING, an object that identifies the day and hour. To learn more, see Day Parting Object.
integer/ enum / object
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:

Table 73 Multiplier Cap 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 /lines/{lineId}/bidmultiplier

Parameters

Table 74 Read Bid Multipliers
Parameter Parameter Type Description Data Type Required?
lineId path Specifies the line ID. integer Y

Example Request

GET /lines/390951/bidmultiplier

Example Response

{ "response” :
[ {
        "id": 521,
        "targetType": "AD",
        "targetValue": 1,
        "multiplier": 1.25
 }, {
        "id": 523,
        "targetType": "AUDIENCE",
        "targetValue": 33,
        "multiplier": 1.65
 }, {
        "id": 524,
        "targetType": "EXCHANGE",
        "targetValue": 17,
        "multiplier": 2.65
 }, {
        "id": 525,
        "targetType": "APP_SITE",
        "targetValue": 3209667,
        "multiplier": 2.65
 }, {
        "id": 527,
        "targetType": "DAY_PARTING",
        "targetValue": {
     "day": "SATURDAY",
     "hour": 23
            },
        "multiplier": 1.1
 }, {
        "id": 526,
        "targetType": "DAY_PARTING",
        "targetValue": {
     "day": "SATURDAY",
     "hour": 11
            },
        "multiplier": 2.1
 }, {
        "id": 528,
        "targetType": "AD_POSITION",
        "targetValue": "PARTIAL_VIEW",
        "multiplier": 0.8
 }, {
        "id": 529,
        "targetType": "DEVICE",
        "targetValue": "TABLET",
        "multiplier": 0.85
 }],
    "errors": null,
    "timeStamp": "2018-02-22T00:24:22Z"
}

Create Bid Multipliers

Creates one or more bidMultiplier objects to the specified line.

A line may be defined by multiple bid multipliers.

Parameters

Table 75 Add Bid Multipliers
Parameter Parameter Type Description Data Type Required?
lineId path Specifies the line ID. integer Y
targetType body

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

  • AD
  • EXCHANGE
  • DAY_PARTING
  • AUDIENCE
  • AD_POSITION
  • APP_SITE
  • DEVICE

To learn more, see Targeting Types and Values.

string Y
targetValue body

Specifies a targetType-specific target value that identifies a targeting attribute.

  • If AD, EXCHANGE, AUDIENCE, or APP_SITE, an integer that identifies a particular targeting attribute. For example, a specific ad ID, exchange ID, or audience ID. To learn more, see Targeting Types and Values.
  • If AD_POSITION or DEVICE, an enum that identifies a particular targeting attribute. To learn more, see Targeting Types and Values.
  • If DAY_PARTING, an object that identifies the day and hour. To learn more, see Day Parting Object.
integer/ enum / object Y
multiplier body

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 Y

Example Request

Note

See Targeting Types and Values for supported target types and their corresponding values. Day parting has special handling.

[{
    "targetType": "AD",
    "targetValue": 1,
    "multiplier": 1.25
}, {
    "targetType": "AUDIENCE",
    "targetValue": 33,
    "multiplier": 1.65
}, {
    "targetType": "EXCHANGE",
    "targetValue": 17,
    "multiplier": 2.65
},  {
    "targetType": "APP_SITE",
    "targetValue": 3209667,
    "multiplier": 2.65
}, {
    "targetType": "DAY_PARTING",
    "targetValue": {
    “saturday” : [1,2,3]

    },
    "multiplier": 1.55
}, {
    "targetType": "DAY_PARTING",
    "targetValue": {
    "saturday": [1]
    },
    "multiplier": 3.25
}, {
    "targetType": "AD_POSITION",
    "targetValue": "PARTIAL_VIEW",
    "multiplier": 0.8
}, {
    "targetType": "DEVICE",
    "targetValue": "TABLET",
    "multiplier": 0.85
}]

Note

Note as can be seen from the example above there could be several blocks defining DAY_PARTING. The idea is to have one block per an unique multiplier value. All blocks will be executed sequentially, means if the same day/same hour occurs more than once last block will set the multiplier value for that time.

Example Response

{ "response” :
[ {
        "id": 521,
        "targetType": "AD",
        "targetValue": 1,
        "multiplier": 1.25
 }, {
        "id": 523,
        "targetType": "AUDIENCE",
        "targetValue": 33,
        "multiplier": 1.65
 }, {
        "id": 524,
        "targetType": "EXCHANGE",
        "targetValue": 17,
        "multiplier": 2.65
 }, {
        "id": 525,
        "targetType": "APP_SITE",
        "targetValue": 3209667,
        "multiplier": 2.65
 }, {
        "id": 527,
        "targetType": "DAY_PARTING",
        "targetValue": {
     "day": "SATURDAY",
     "hour": 23
            },
        "multiplier": 1.1
 }, {
        "id": 526,
        "targetType": "DAY_PARTING",
        "targetValue": {
     "day": "SATURDAY",
     "hour": 11
            },
        "multiplier": 2.1
 }, {
        "id": 528,
        "targetType": "AD_POSITION",
        "targetValue": "PARTIAL_VIEW",
        "multiplier": 0.8
 }, {
        "id": 529,
        "targetType": "DEVICE",
        "targetValue": "TABLET",
        "multiplier": 0.85
 }],
    "errors": null,
    "timeStamp": "2018-02-22T00:24:22Z"
}

Update Bid Multiplers

Updates the bid multipliers associated with a line.

PUT /lines/{lineId}/bidmultiplier

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

Parameters

The only required parameter is the lineId, which is specified in the path of the endpoint URL. All other parameters are specified in the body of the application/json payload.

Table 76 Update Bid Multipliers
Parameter Parameter Type Description Data Type Required?
lineId path Specifies the line ID number. integer Y
added body Specifies an array of bidMultipler objects. For an example, see Example Request. 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. For an example, see Example Request. array N
removed body Specifies an array of bid mulipliers identified by their id numbers. For an example, see Example Request. array N

Example Request

The lineId is specified in the path of the endpoint.

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

All other parameters are specified in the body of the application/json payload. The payload can consists of three objects: an added array of bidMulitipler objects, a removed array of bid multiplier id integers, and an edited array of updated bidMultiplier object attributes:

{
    "added": [{
        "targetType": "DAY_PARTING",
        "targetValue": {
            "sunday": [14]
        },
        "multiplier": 0.5
    }],
    "removed": [521],
    "edited": [{
        "id": 527,
        "targetType": "DAY_PARTING",
        "targetValue": {
        "sunday": [1, 2, 19],
        "tuesday": [],
        "wednesday": [2, 3, 4]
    },
    "multiplier": 3.05
    }
  ]
}

Example Response

{ "response” :
[ {
     "id": 521,
     "targetType": "AD",
     "targetValue": 1,
     "multiplier": 1.25
 }, {
     "id": 523,
     "targetType": "AUDIENCE",
     "targetValue": 33,
     "multiplier": 1.65
 }, {
     "id": 524,
     "targetType": "EXCHANGE",
     "targetValue": 17,
     "multiplier": 2.65
 }, {
     "id": 525,
     "targetType": "APP_SITE",
     "targetValue": 3209667,
     "multiplier": 2.65
 }, {
     "id": 527,
     "targetType": "DAY_PARTING",
     "targetValue": {
    "sunday": [1, 2, 19],
    "tuesday": [],
    "wednesday": [2, 3, 4]
     },
     "multiplier": 1.1
 }, {
     "id": 526,
     "targetType": "DAY_PARTING",
     "targetValue": {
    "saturday": [1, 2, 3]
     },
     "multiplier": 1.1
 }, {
     "id": 528,
     "targetType": "AD_POSITION",
     "targetValue": "PARTIAL_VIEW",
     "multiplier": 0.8
 }, {
     "id": 52=9,
     "targetType": "DEVICE",
     "targetValue": "TABLET",
     "multiplier": 0.85
 }],
    "errors": null,
    "timeStamp": "2018-02-22T00:24:22Z"
}

Read Multiplier Caps

Reads the multiplierCap value of the specified line.

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

Table 77 Reads Bid Multiplier Caps
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/maxmultipliedcpm

Example Response

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

Status and Error Codes

Table 78 Status and Error Codes
Status Code Description
200 The request has succeeded.

Add Multiplier Caps

Specifies the multiplierCap value for the specified line.

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

Table 79 Add Bid Multiplier Caps
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

Table 80 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 Caps

Updates the multiplierCap value for the specified line.

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.

Table 81 Update Bid Multiplier Caps
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

Table 82 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.