Yahoo Native Bid Multipliers

This article describes services for reading, adding, removing and updating bid multipliers for |co| native lines.

Overview

You can use bid multipliers to increase or decrease your bids based on supply attributes or audiences. For example, an ad served to a mobile phone on a specific site or group of sites may be more valuable to your campaign than an ad served to a desktop, and you may be willing to bid more for those ad placements.

Using bid multipliers, you can specify multiplier values that affect the amount a line can bid for targeted opportunities. For details, see Bid Multipliers Overview in the DSP UI help center.

Use the Bid Multipliers resource to read, add, update and remove bid multipliers on lines. See the Bid Multipliers help page in the Traffic API for details on the full specifications of the resource. This section focuses on Bid Multiplier target types supported for Yahoo native lines.

Endpoint

/traffic/lines/<lineId>/bidmultipliers

Supported Bid Multiplier Target Types

The following table lists the bid multipliers that DSP supports for Yahoo native lines.

Note

The target types listed below are the only ones supported on bid multipliers of Yahoo native lines.

Target Type

Description

Target Value

Sample

SUPPLY_GROUP

Use the Supply Group target type to modify bids on aggregated groups of sites and devices. Use the Bid Multiplier Targets resource to learn more on what each available supply group target represents.

A Long value that identifies the Supply Group on which the bid multiplier should be applied.

1

SITE_X_DEVICE

Use the Site X Device target type to modify bids on a specific combination of site and device. (Eg: Yahoo Homepage US and Mobile)

A Long value that identifies the combination of website and device on which the bid multiplier should be applied.

80

SITE_GROUP_X_DEVICE

Use the Site Group X Device bid modifier to modify bids on a per-site group, per-device basis on selected site groups.

A Long value that identifies the combination of site group and device on which the bid multiplier should be applied.

472

DAY_PARTING

Use the Day Parting target type to modify bids for different parts of the day.

An object that identifies day and hour day-parting values on which the bid multiplier should be applied.

{“day”: “SUN”, “hour”: 14}

Read

To view the current bid multipliers applied to a line, send a GET request to the bid multipliers endpoint. For details on the response attributes, see the Bid Multipliers help page in the Traffic API.

Example Request

GET /traffic/lines/2222/bidmultipliers HTTP/1.1
Host: <HOST_NAME>
Content-Type: application/json
Accept: application/json
X-Auth-Method: OAuth2
X-Auth-Token: <ACCESS_TOKEN>

Example Response

{
  "response": {
     "bidMultipliers": [
         {
             "id": 1212,
             "targetType": "SUPPLY_GROUP",
             "targetValue": 1,
             "multiplier": 1.5
         },
         {
             "id": 1213,
             "targetType": "SITE_X_DEVICE",
             "targetValue": 280,
             "multiplier": 2.5
         },
         {
             "id": 531,
             "targetType": "DAY_PARTING",
             "targetValue": {
               "day": "SUN",
               "hour": 14
             },
             "multiplier": 0.5
         }
     ],
     "bidMultiplierCap": null
  },
  "errors": null,
  "timeStamp": "2020-03-31T03:35:08.960Z"
}

Add - Remove - Update

To add, remove or update bid multipliers, send a POST request to the bid multipliers endpoint with added, removed, edited or removedItems arrays. To learn more about these arrays, see the Bid Multipliers help page in the Traffic API.

Note

The field removed is planned for deprecation in favor of removedItems. Please plan for migration if your current implementation uses removed.

To add new bid multipliers, the client needs to be aware of the supported targetTypes and targetValues. For targetTypes, see Supported Bid Multiplier Target Types.

Use the Bid Multiplier Targets resource to fetch supported targetValues. Target values represent the site-device combinations available for lines to apply bid multipliers on. For example, targetValue = 280 with targetType = SITE_X_DEVICE represents “News US - Mobile” = Yahoo News (US) on Mobile. Applying a multiplier of 1.5 using this set of targetType, targetValue and multiplier makes the line bid 1.5 times the regular bid on an ad opportunity coming from Yahoo News on a mobile device.

To edit or remove an existing bid multiplier on a line, the client needs to know the unique id of the bid multiplier. To get ids of all bid multipliers on a line, use the Read method.

Note

The default multiplier for all targets is 1.0. This means creating a bid multiplier with multiplier value 1.0 is equivalent to not having a bid multiplier on that target. When a user chooses to update the multiplier value of an existing bid multiplier to 1.0, the client may choose to remove the bid multiplier - the effect will be the same as adding it to the edited array with multiplier = 1.0.

Example Request

POST /traffic/lines/2222/bidmultipliers HTTP/1.1
Host: <HOST_NAME>
Content-Type: application/json
Accept: application/json
X-Auth-Method: OAuth2
X-Auth-Token: <ACCESS_TOKEN>
{
  "added": [
     {
        "targetType": "SITE_X_DEVICE",
        "targetValue": 201,
        "multiplier": 0.7
     },
     {
        "targetType": "SITE_GROUP_X_DEVICE",
        "targetValue": 401,
        "multiplier": 2.5
     },
     {
        "targetType": "SUPPLY_GROUP",
        "targetValue": 4,
        "multiplier": 2.6
     }
     {
        "targetType": "DAY_PARTING",
        "targetValue": {
          "day": "MON",
          "hour": 10
        },
        "multiplier": 0.5
     }
  ],
  "removed": [
    1213
  ],
  "edited": [
     {
        "id": 1212,
        "targetType": "SUPPLY_GROUP",
        "targetValue": 1,
        "multiplier": 2.5
     }
  ],
  "removedItems": [
    {
      "id": 575,
      "targetType": "SITE_X_DEVICE"
    },
    {
      "id": 580,
      "targetType": "DAY_PARTING"
    }
  ]
}

Example Response

{
  "response": {
     "bidMultipliers": [
           {
              "id": 1212,
              "targetType": "SUPPLY_GROUP",
              "targetValue": 1,
              "multiplier": 2.5
           },
           {
              "id": 1214,
              "targetType": "SUPPLY_GROUP",
              "targetValue": 4,
              "multiplier": 2.6
           },
           {
              "id": 1215,
              "targetType": "SITE_X_DEVICE",
              "targetValue": 201,
              "multiplier": 0.7
           },
           {
              "id": 1216,
              "targetType": "SITE_GROUP_X_DEVICE",
              "targetValue": 401,
              "multiplier": 2.5
           },
           {
              "targetType": "DAY_PARTING",
              "targetValue": {
                "day": "MON",
                "hour": 10
              },
              "multiplier": 0.5
           }
     ],
     "bidMultiplierCap": null
  },
  "errors": null,
  "timeStamp": "2020-03-31T03:36:08.960Z"
}