Bid Multipliers
  • 12 Minutes to read

    Bid Multipliers


      Article summary

      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, refer to 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, refer to 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, refer to 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, refer to 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, refer to 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, refer to 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, refer to 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, refer to 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, 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.

      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, refer to Targeting Types and Values.

      string

      targetValue

      Specifies a value that is determined by the targetType.

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

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

      • If DAY_PARTING: an object that represents the day and hour. To learn more, refer to 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 opportunities 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, refer to Bid Multiplier Bid Price Calculation.

      number

      name

      Is a read only field. Specifies the name for the targeted bid for a few target types such as SUPPLY_GROUP, SITE_X_DEVICE and SITE_GROUP_X_DEVICE.

      string

      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 opportunities that satisfy the targeting attributes specified for two or more bid multipliers. To learn more, refer to 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
            },
            {
              "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.

      Parameter

      Parameter Type

      Description

      Data Type

      Required

      lineId

      path

      Specifies the line ID number.

      integer

      Y

      added

      body

      Specifies an array of bidMultiplier objects.

      array

      N

      edited

      body

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

      array

      N

      removed

      body

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

      array

      N

      removedItems

      body

      Specifies an array of objects. Each object consists of a key-value pair that identifies the bid multiplier by its id number and bidMultiplier fields.

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

      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, refer to 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, 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.

      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.


      Was this article helpful?

      What's Next