About Targeting

This article describes resources that enable you to read and define line targeting.

Overview

Oath Ad Platforms DSP enables you to target exchanges, deals, locations, demographics, ad positions, frequency, audiences, devices, days of the week, apps, URLs, page relevancy, mobile carriers, and languages.

Targeting Types

Your ability to target consumers is constrained by the creatives served by the line.

The Oath Ad Platforms DSP supports the following targeting types:

Targeting Type Description Display Video Native
AB_TESTING If you have created user groups for A/B testing, you can target those user groups to see the results of your testing. Y Y N
AD_INITIATION For video ads, you can set the type of ad initiation you want to target (Auto Initiated, User Initiated, Unknown, or All). N Y N
AD_POSITION Target the location on a page that you want your display ads to appear. Y N N
BOT Note: Only available via special role. Ensure your ads are properly represented and delivered to real people, rather than to bot traffic. Y Y N
CONNECTION

You can target users based on how they are connected to the internet (wi-fi, cellular, or both). You can also target Internet Service Providers (ISPs) and Mobile Carriers, as follows:

  • If you target wi-fi customers, you can also target users connected through particular ISPs.
  • If you target cellular users, you can also target users connected through particular mobile carriers.
  • If you target All connection types, you can target both ISPs and mobile carriers.

Important: If you target both ISPs and mobile carriers, the targeting uses OR logic and targets a user who is connected through either an ISP or a mobile carrier you choose.

Y Y N
CONTEXTUALS If you have created contextuals for an advertiser, you can set up targeting to serve or exclude ads based on the contextual. Y Y N
DAY_PARTING Choose the days and times your display or video ads should serve. Y Y N
DEMOGRAPHIC Reach your desired audience with age and gender targeting. Y Y Y
EXCHANGES A line can target one or more exchanges or available private marketplace deals (but not both). Y Y N
FREQUENCY_CAPPING Set a limit on how frequently an ad is shown to a user within a specified time frame. Y Y N
GEOGRAPHY

Location targeting enables you to target specific geographical areas. You can target a country, state, city, Nielsen Designated Marketing Area (DMA), ZIP or postal code, or a geofencing location.

Native lines can only target by Country/State/City/DMA.

You can set up geofencing to target users within a specified radius of a given address.

Y Y Y
INVENTORY_TYPE You can explictly target web vs. in-app supply. Y Y Y
LANGUAGES Target lines based on the language users most frequently view in their browsers. Advertisers can target or exclude specific languages. Y Y N
MOBILE_PLACEMENT Enable targeting of consumers with intersitial and rewarded ads. Y Y N
PLAYER_SIZE Enable targeting based on the player size. N Y N
SEGMENT If you have created audiences or pixels (beacons), you can perform line item targeting using include and exclude conditions. Native lines can target audiences but not pixels. Y Y Y
SITE_LISTS If you have set app lists and/or site lists to include and/or exclude apps and URLs, you can target those app lists and/or site lists. Y Y N
TECHNOLOGY Target users based on the technologies in their computing environment such as device type, operating system (desktop and mobile) and browser. Y Y Y
VIEWABILITY You can set hard viewability goals for display and video line items. When you set a viewability threshold for a line item, viewability takes precedence over line item delivery, and you can expect line items to achieve and maintain the viewability goal. Y Y N

End Points

The following endpoint enables you to read the resources targeted by a line using the GET method:

/traffic/targeting/{object}

The Oath Ad Platforms DSP API provides unique endpoints for each target type.

The following endpoint enables you to add and update line targeting using the PUT and POST methods:

/traffic/lines/{id}/targeting

Resources

Targeting Object

The targeting resource is the standard Oath Ad Platforms DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

This resource comprises multiple fields that enable you to specify line targeting across many types of targets including the SEGMENT, EXCHANGES, and CONNECTION target types.

Note

Read-only fields are returned by Read Line Targeting requests.

Field Description Data Type Target Type
genders

Specifies the genders targeted.

  • MALE
  • FEMALE
  • UNKNOWN
  • ALL
array DEMOGRAPHIC
ages

Specifies the age ranges targeted.

  • 18-20
  • 21-24
  • 25-34
  • 35-44
  • 45-49
  • 50-54
  • 55-64
  • 65+
  • UNKNOWN
  • ALL
array DEMOGRAPHIC
threshold

Specifies the acceptable in-target audience composition percentage for video ads.

The value indicates the percentage of impressions that reach the intended demographic.

  • 20
  • 30
  • 40
  • 50
  • 60
  • 70
  • 80

Note: This field is valid when campaign targeting verification vendor is not Yahoo.

integer FREQUENCY_CAPPING
frequencyCapPeriod

Specifies the frequency cap interval.

  • MINUTES
  • HOURLY
  • DAILY
  • WEEKLY
  • UNLIMITED - No limit to the number of times the ad can be displayed.
string FREQUENCY_CAPPING
frequencyCapValue

Specifies the number of imporessions all for the selected frequencyCapPeriod. If frequencyCapPeriod selected is:

  • UNLIMITED - Do not provide frequencyCapPeriod in the payload.
  • MINUTES - The maximum time limit allowed for a minute is 5.
  • HOURLY - The maximum time limit allowed for a hour is 10.
  • DAILY - The maximum time limit allowed for a day is 20.
  • WEEKLY - The maximum time limit allowed for a week is 140.
  • MONTHLY - The maximum time limit allowed for a month is 600.
string FREQUENCY_CAPPING
serveUnknownUser

Specifies whether the ad is served to known or unknown users:

  • If true, serve to unknown users.
  • If false, serve to known users only.
boolean FREQUENCY_CAPPING
dayParting

Specifies the days of the week and hours of the day targeted.

To learn more, see Day Parting Targeting.

object DAY_PARTING
languages

Specifies the languages targeted:

  • UNKNOWN
  • ENGLISH
  • CHINESE
  • SPANISH
  • JAPANESE
  • PORTUGUESE
  • GERMAN
  • ARABIC
  • FRENCH
  • RUSSIAN
  • DUTCH
  • SWEDISH
  • ITALIAN
  • INDONESIAN
  • ALL
array LANGUAGES
inventoryTypes

Specifies the inventory types targeted:

  • WEB
  • APP
array INVENTORY_TYPE
bots

Specifies the bot fraud prevention partner:

  • DOUBLE_VERIFY
  • IAS
array BOT
userGroupEntry

Specifies the user group entry.

For POST, you need to supply the id field, not the entire object.

object AB_TESTING
deviceTypes

Specifies the device types targeted:

  • DESKTOP
  • PHONE
  • TABLET
  • UNKNOWN
  • ALL
array TECHNOLOGY
os

Specifies the operating system types targeted:

  • MAC
  • WINDOWS
  • LINUX
  • OTHER
  • ALL
array TECHNOLOGY
browsers

Specifies the browser types targeted.

Note: deviceTypes must be set to DESKTOP to target browsers.

array TECHNOLOGY
mobileOs

Specifies the mobile OS types targeted.

Note: deviceTypes must be set to PHONE or TABLET to target mobileOs.

array TECHNOLOGY
adInitiations

For video ads, specifies how the targeted ad is initiated:

  • AUTOINITIATED - The video starts without any user action.
  • USERINITIATED - The video starts only if the user clicks Play.
  • ANDROID
  • UNKNOWN
  • ALL
array AD_INITIATION
positions

For display ads, specifies location on the page where the ad appears:

  • ABOVE_FOLD - The ad serves on the top 50% of the page.
  • PARTIAL_VIEW - The ad serves when at least 25% of the ad is visible. .
  • BELOW_FOLD - The ad serves on the bottom 50% of the page.
  • UNKNOWN - The ad serves in an unknown position.
  • ALL
array AD_POSITION
playerSizes

For video ads, the platform determines the player size based on height and width (in pixels) specified in the bid request. The platform extracts the larger of the two and assigns a player size:

  • SMALL - Less than 350 pixels
  • MEDIUM - 350 to 500 pixels
  • LARGE - Greater than or equal to 500 pixels
  • UNKNOWN
  • ALL
array PLAYER_SIZE
inviewThreshold Specifies the viewability rate threshold. A value between 1-100. number VIEWABILITY
publishers

Specifies the publishers/exchanges targeted. To learn more, see Exchange Targeting.

Note: For POST, you need to supply only the id values in an array, not the entire publisher object.

Note: You can not target both publishers and deals at the same time.

array EXCHANGES
mobileCarriers

Specifies the mobile carriers and ISPs targeted.

Note: To target a mobile carrier, you need only specify the id field only.

array CONNECTION
types

Specifies the targeting types enabled and disabled for the line.

To learn more, see Targeting Types.

array N/A
deals

Specifies private marketplace deals to target.

array EXCHANGES
contextuals

Specifies contexutals to target or exclude from targeting.

array CONTEXTUALS
siteLists

Specifies site lists and app lists to target or exclude from targeting.

array SITE_LISTS
geos

Specifies geographic locations to target or exclude from targeting.

  • To create or update targeted geographic locations, see Geo.
  • To read geographic locations that can be targeted, see Read Geos to Target.

Note: You cannot target both geographic locations and geofencing locations at the same time.

array GEOGRAPHY
geoFencings

Specifies geo fencing locations to target or exclude from targeting.

To create or update targeted geo fencing locations, see Geo Fencing.

Note: You cannot target both geographic locations and geofencing locations at the same time.

array GEOGRAPHY
segments

Specifies segments to target or exclude from targeting.

Note: You can target both segments and beacons at the same time.

array SEGMENT
beacons

Specifies beacons to target or exclude from targeting.

Note: You can target both segments and beacons at the same time.

object BEACONS
dealsIncluded

A read-only array that specifies the deals included in targeting.

To learn more, see Exchange Targeting.

array EXCHANGES
contextualsIncluded

A read-only array that specifies the contextuals included in targeting.

To learn more, see Contextuals Targeting.

array CONTEXTUALS
contextualsExcluded

A read-only array that specifies the contextuals excluded from targeting.

To learn more, see Contextuals Targeting.

array CONTEXTUALS
siteListsIncluded A read-only array of site lists and app lists that are included in targeting. To learn more, see Site List Targeting. array SITE_LISTS
siteListsExcluded A read-only array of site lists and app lists that are excluded from targeting. To learn more, see Site List Targeting. array SITE_LISTS
geosIncluded

A read-only array of geo locations included in targeting.

To learn more, see Geos Included Object.

array GEOGRAPHY
geosExcluded

A read-only array of geofencing locations excluded from targeting by the line.

To learn more, see Geos Excluded Object¶.

array GEOGRAPHY
geoFencingsIncluded

A read-only array of geofencing locations included in targeting by the line.

To learn more, see Geo Fencing.

array GEOGRAPHY
segmentsIncluded

A read-only array that shows the segments included in targeting.

To learn more, see Segments Included Object.

array SEGMENT
segmentsExcluded

A read-only array that shows the segments excluded from targeting.

To learn more, see Segments Included Object.

array SEGMENT
beaconsIncluded

A read-only array that shows the beacons included in targeting.

To learn more, see Beacons Included Object.

array SEGMENT
beaconsExcluded

A read-only array that shows the beacons excluded from targeting.

To learn more, see Beacons Included Object.

array SEGMENT

Target Types Object

When reading (GET) existing line targeting, the types payload object shows all the targeting types which are enabled for the line.

When creating or updating (POST) line targeting, the types payload object contains all the targeting types which are to be enabled or modified.

Name Description Data Type
id Specifies the target type. integer
name

Specifies the name of the target type.

For a complete list of target types, see target-types.

string
isTargeted

Specifies whether the target type is enabled or disabled for the line.

  • If true, the target type is enabled.
  • If false, the target type is disabled.
boolean

Example Payload (Partial)

{
  "types": [
    {
      "id": 8,
      "isTargeted": true,
      "name": "DAY_PARTING"
    },
    {
      "id": 3,
      "isTargeted": true,
      "name": "AD_POSITION"
    }
  ]
}

Read Line Targeting

Returns targeting data for the specific line.

GET /traffic/lines/{id}/targeting

Parameters

Table 125 Read Line Targeting Parameters
Name Parameter Type Description Data Type Required
id path Specifies the ID of line. integer Y

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting

Example Response

The response returns information about target types the targeted by the line.

{
"response": {
        "types": [
                {
                        "name": "GEOGRAPHY",
                        "id": 4,
                        "isTargeted": true
                },
                {
                        "name": "PLAYER_SIZE",
                        "id": 14,
                        "isTargeted": true
                },
                {
                        "name": "TARGET_VIEWABILITY",
                        "id": 13,
                        "isTargeted": false
                },
                {
                        "name": "AD_INITIATION",
                        "id": 15,
                        "isTargeted": true
                },
                {
                        "name": "VIEWABILITY",
                        "id": 24,
                        "isTargeted": true
                },
                {
                        "name": "VIDEO_INVENTORY",
                        "id": 25,
                        "isTargeted": true
                },
                {
                        "name": "DEMOGRAPHIC",
                        "id": 6,
                        "isTargeted": true
                },
                {
                        "name": "FREQUENCY_CAPPING",
                        "id": 1,
                        "isTargeted": true
                },
                {
                        "name": "AB_TESTING",
                        "id": 10,
                        "isTargeted": true
                },
                {
                        "name": "SEGMENT",
                        "id": 12,
                        "isTargeted": true
                },
                {
                        "name": "TECHNOLOGY",
                        "id": 7,
                        "isTargeted": true
                },
                {
                        "name": "DAY_PARTING",
                        "id": 8,
                        "isTargeted": false
                },
                {
                        "name": "SITE_LISTS",
                        "id": 9,
                        "isTargeted": true
                },
                {
                        "name": "CONTEXTUALS",
                        "id": 2,
                        "isTargeted": true
                },
                {
                        "name": "EXCHANGES",
                        "id": 11,
                        "isTargeted": true
                },
                {
                        "name": "MOBILE",
                        "id": 16,
                        "isTargeted": true
                },
                {
                        "name": "LANGUAGES",
                        "id": 19,
                        "isTargeted": true
                },
                {
                        "name": "SEAT_LEVEL_SITE_LISTS",
                        "id": 20,
                        "isTargeted": true
                },
                {
                        "name": "BOT",
                        "id": 21,
                        "isTargeted": true
                },
                {
                        "name": "INVENTORY_TYPE",
                        "id": 26,
                        "isTargeted": true
                }
        ],
        "mobileCarriers":[
                1
        ],
        "isps":[
                115
        ],
        "genders": [
                "MALE",
                "FEMALE"
        ],
        "ages": [
                "55-64",
                "65+",
                "18-20",
                "21-24",
                "45-49",
                "50-54"
        ],
        "days": [
                "ALL"
        ],
        "deviceTypes": [
                "UNKNOWN",
                "TABLET"
        ],
        "os": [
                "ALL"
        ],
        "browsers": [
                "ALL"
        ],
        "mobileOs": [
                "ANDROID",
                "RIM"
        ],
        "mobileCarriers": [
                "Verizon"
        ],
        "isps": [
                "Colt Technology Services"
        ],
        "languages": [
                "ENGLISH",
                "GERMAN"
        ],
        "inventoryTypes": [
                "APP"
        ],
        "playerSizes": [
                "MEDIUM",
                "LARGE"
        ],
        "adInitiations": [
                "USERINITIATED"
        ],
        "bots": [
                "DOUBLE_VERIFY"
        ],
        "positions": [
                "ALL"
        ],
        "userGroupEntry": {
                "id": 32659,
                "name": "sg2",
                "userGroupId": 14962,
                "trafficPercent": 56,
                "lowerBound": 0,
                "upperBound": 55
        },
        "frequencyCapPeriod": "HOURLY",
        "contextualsIncluded": [
                {
                        "taxonomyType": "IAB",
                        "id": 43505,
                        "accountId": 7987,
                        "name": "iabtest5566",
                        "updatedAt": "2017-08-01T22:08:52Z",
                        "categories": [
                                {
                                        "id": 132269,
                                        "categoryId": 107
                                },
                                {
                                        "id": 132270,
                                        "categoryId": 102
                                }
                        ]
                }
        ],
        "contextualsExcluded": [
                {
                        "taxonomyType": "DOUBLE_VERIFY",
                        "id": 43236,
                        "accountId": 7987,
                        "name": "contextual_update_test",
                        "updatedAt": "2017-07-17T23:58:28Z",
                        "categories": [
                                {
                                        "id": 131535,
                                        "categoryId": 6
                                },
                                {
                                        "id": 131536,
                                        "categoryId": 9
                                }
                        ]
                }
        ],
        "siteListsIncluded": [
                {
                        "status": "ACTIVE",
                        "type": "SITE_LIST",
                        "id": 47539,
                        "name": "TestSiteList_1459797912042",
                        "accountId": 318286,
                        "isShared": true,
                        "updatedAt": "2016-04-04T19:25:12Z",
                        "childrenCount": 1,
                        "items": [
                                {
                                        "id": 1019678,
                                        "itemName": "yahoo.com"
                                }
                        ]
                }
        ],
        "siteListsExcluded": [
                {
                        "status": "ACTIVE",
                        "type": "APP_LIST",
                        "id": 56919,
                        "name": "Test Mobile 11/28",
                        "accountId": 1,
                        "isShared": true,
                        "updatedAt": "2016-11-29T01:00:47Z",
                        "childrenCount": 1,
                        "items": [
                                {
                                        "id": 1978914,
                                        "itemName": "com.myyearbook.m"
                                }
                        ]
                }
        ],
        "publishers": [
                {
                        "id": 3,
                        "name": "BRXD"
                },
                {
                        "id": 4,
                        "name": "Rubicon"
                },
                {
                        "id": 67,
                        "name": "AdForm(BSW)"
                },
                {
                        "id": 74,
                        "name": "A9"
                }
        ],
        "geosIncluded": [
                {
                        "id": "###ab#can",
                        "name": "Alberta, Canada",
                        "description": "alberta",
                        "level": "State",
                        "key": "ab, can",
                        "excluded": false
                },
                {
                        "id": "####can",
                        "name": "Canada",
                        "description": "canada",
                        "level": "Country",
                        "key": "can",
                        "excluded": false
                },
                {
                        "id": "###15#nor",
                        "name": "More Og Romsdal, Norway",
                        "description": "more og romsdal",
                        "level": "State",
                        "key": "15, nor",
                        "excluded": false
                }
        ],
        "geosExcluded": [
                {
                        "id": "##callahan#fl#usa",
                        "name": "Callahan, Florida",
                        "description": "callahan, fl",
                        "level": "City",
                        "key": "callahan, florida",
                        "excluded": true
                }
        ],
        "segmentsIncluded": [
                {
                        "id": "20604896",
                        "name": "Penny Dreadful S3 BrightRoll Test",
                        "recency": 30,
                        "createdAt": "2015-12-08",
                        "audienceType": "3rd Party",
                        "segmentType": "COMPOSITE",
                        "reachCount": 449491095
                }
        ],
        "segmentsExcluded": [
                {
                        "id": "50348744",
                        "name": "FlyWheel Studio Test",
                        "recency": 90,
                        "createdAt": "2017-10-13",
                        "audienceType": "3rd Party",
                        "segmentType": "COMPOSITE",
                        "reachCount": 617452399
                },
                {
                        "id": "20703845",
                        "name": "MB Test - HHI 75k+",
                        "recency": 30,
                        "createdAt": "2016-05-04",
                        "audienceType": "3rd Party",
                        "segmentType": "COMPOSITE",
                        "reachCount": 135984850
                }
        ],
        "beaconsIncluded": [
                {
                        "id": "6436593",
                        "name": "DesTest Website Int 0",
                        "recency": 30,
                        "frequency": 7
                }
        ],
        "beaconsExcluded": [
                {
                        "id": "6434432",
                        "name": "deswebsite new0",
                        "recency": 50,
                        "frequency": 1
                }
        ],
        "threshold": 40,
        "frequencyCapValue": 2,
        "serveUnknownUser": true,
        "inviewThreshold": 2
},
"errors": null,
"timeStamp": "2018-01-12T01:57:40Z"
}

Add/Update Line Targeting

Adds or updates the specified targets for the specified line.

POST traffic/lines/{id}/targeting/

Parameters¶

All requests to add or update targets to a line require the following parameters:

Table 126 Add/Update Line Targeting Parameters
Name Parameter Type Description Data Type Required
id path Specifies the ID of line. integer Y
types body

Specifies an array of Targeting Type objects that identify the targeting type and whether it is targeted by the line.

  • If true, the line targets the specified targeting type.
  • If false, the line does not target the specified targeting type.

To learn more, see Targeting Types.

array Y
genders body

Specifies the genders targeted.

To learn more, see Demographic Targeting.

array N
ages body

Specifies the age ranges targeted.

To learn more, see Demographic Targeting.

array N
threshold body

Specifies the acceptable in-target audience composition percentage for video ads.

To learn more, see Frequency Capping Targeting.

integer N
frequencyCapPeriod body

Specifies the frequency cap interval.

To learn more, see Frequency Capping Targeting.

string N
frequencyCapValue body

Specifies the number of impressions all for the selected frequencyCapPeriod.

To learn more, see Frequency Capping Targeting.

string N
serveUnknownUser body

Specifies whether the ad is served to known or unknown users.

To learn more, see Frequency Capping Targeting.

boolean N
dayParting body

Specifies the days of the week and hours of the day targeted.

To learn more, see Day Parting Targeting.

object N
languages body

Specifies the languages targeted:

  • UNKNOWN
  • ENGLISH
  • CHINESE
  • SPANISH
  • JAPANESE
  • PORTUGUESE
  • GERMAN
  • ARABIC
  • FRENCH
  • RUSSIAN
  • DUTCH
  • SWEDISH
  • ITALIAN
  • INDONESIAN
  • ALL

To learn more, see Language Targeting.

array N
inventoryTypes body

Specifies the inventory types targeted.

To learn more, see Language Targeting.

array N
bots body

Specifies the bot fraud prevention partner.

To learn more, see Bot Targeting.

array N
userGroupEntry body

Specifies the user group to target.

To learn more, see A/B Testing Targeting.

object N
deviceTypes body

Specifies the device types targeted.

To learn more, see Technology Targeting.

array N
os body

Specifies the operating system types targeted.

To learn more, see Technology Targeting.

array N
browsers body

Specifies the browser types targeted.

To learn more, see Technology Targeting.

Note: deviceTypes must be set to DESKTOP to target browsers.

array N
mobileOs body

Specifies the mobile OS types targeted.

To learn more, see Technology Targeting.

Note: deviceTypes must be set to PHONE or TABLET to target mobileOs.

array N
adInitiations body

For video ads, specifies how the targeted ad is initiated.

To learn more, see Ad Initiation Targeting.

array N
positions body

For display ads, specifies location on the page where the ad appears:

To learn more, see Ad Position Targeting.

array N
playerSizes body

For video ads, the platform determines the player size based on height and width (in pixels) specified in the bid request. The platform extracts the larger of the two and assigns a player size.

To learn more, see Player Size Targeting.

array N
inviewThreshold body

Specifies the viewability rate threshold.

To learn more, see Viewability Targeting.

integer N
publishers body

Specifies the publishers/exchanges targeted.

To learn more, see Exchange Targeting.

Note: For POST, you need to supply only the id values in an array, not the entire publisher object.

Note: You can not target both publishers and deals at the same time.

array N
mobileCarriers body

Specifies the mobile carriers and ISPs targeted.

To learn more, see Connection Targeting.

Note: To target a mobile carrier, you need only specify the id field only.

array MAGPIE
deals body

Specifies private marketplace deals to target.

To learn more, see Exchange Targeting.

array N
contextuals body

Specifies contextuals to target or exclude from targeting.

To learn more, see Contextuals Targeting.

array N
siteLists body

Specifies site lists and app lists to target or exclude from targeting.

To learn more, see Site List Targeting.

array N
geos body

Specifies geographic locations to target or exclude from targeting.

To learn more, see Geography Targeting.

Note: You cannot target both geographic locations and geofencing locations at the same time.

array N
geoFencings body

Specifies geofencing locations to target or exclude from targeting.

To learn more, see Geography Targeting.

Note: You cannot target both geographic locations and geofencing locations at the same time.

array N
segments body Specifies segments to target or exclude from targeting. array N
beacons body

Specifies beacons to target or exclude from targeting.

Note: You can target both segments and beacons at the same time.

array N

For each targeting type the line targets, you must specify the payload for that target.

Example Request

The line ID is specified in the path of the resource endpoint:

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting

All other parameters are specified in the body of the application/json payload.

{
  "bots": [
    "IAS"
  ],
  "types": [
    {
      "name": "BOT",
      "isTargeted": true
    }
  ]
}