Segment Targeting

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

Overview

If you have created audiences, you can target consumers based on those audiences using include and exclude conditions.

The Yahoo DSP supports SEGMENT targeting for lines serving display, video, and native ads.

Endpoint

Read Segments

The Yahoo DSP API provides an endpoint for reading the segments available for targeting:

GET /traffic/targeting/availablesegments

Read Targeted Segments

The Yahoo DSP API provides an endpoint for identifying the segments currently targeted by a line.

GET /traffic/lines/{id}/targeting

To learn more, refer to Read Line Targeting.

Target Segments

The Yahoo DSP API provides a single endpoint to add, update, remove, and clear the segments targeted by a line.

POST /traffic/lines/{id}/targeting

This is the same endpoint that is used for all targeting operations. The line ID must be specified in the endpoint path. All other parameters are specified in the body of the application/json payload. To learn more, refer to About Targeting.

Resources

Targeting Object

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

Parameter

Parameter Type

Definition

Data Type

Required

id

path

Specifies the line ID.

integer

Y

segments

body

Specifies an array of segments to include in or exclude from line targeting. To learn more, refer to Segments Object.

array

Y

segmentsIncluded

body

A read-only array that shows the segments included in targeting. To learn more, refer to Segments Included Object.

array

N/A

segmentsExcluded

body

A read-only array that shows the segments excluded from targeting. To learn more, refer to Segments Excluded Object.

array

N/A

types

body

Specifies an array of targeting types to update, enable, or disable.

SEGMENT targeting type must be specified to apply the changes.

To learn more, refer to Targeting Types.

array

Y

Note

For a complete list of targeting resource fields, refer to About Targeting.

Segments Object

The segments payload object enables you to Add/Update Segment Targeting, update-segments, remove-segments, or clear-all-segments targeted by a line.

Field

Description

Data Type

id

Specifies the line ID.

integer

types

Specifies the targeting types to enable or modify. To learn more, refer to Targeting Types.

array

added

An array of segments to target. This is an array of objects containing the following required fields:

  • entityId - Specifies the segment ID.

  • excluded - Indicates whether the added segments are to be excluded or included. If true, exclude from targeting. If false, include in targeting.

    For an example, refer to Add/Update Segment Targeting.

array

edited

An array of existing segments/audiences to change. This is an array of objects containing the following fields:

  • entityId - ID of the Segment to be changed.

  • excluded - Indicates if the edited IDs are to be excluded or included. true - exclude from targeting; false - include in targeting.

    For an example, refer to update-segments.

array

removed

An array of segment IDs to be removed from targeting.

For an example, refer to remove-segments.

array

clearAll

Indicates if all existing segments should be removed. By default, false.

  • If true, remove all targeted segments.

  • If false, do not remove any targeted segments.

For an example, refer to clear-all-segments.

boolean

Segments Included Object

The Read Line Targeting API returns the segmentsIncluded and segmentsExcluded objects along with other data about line targeting.

The segmentsIncluded object is a read-only object that displays information about the segments targeted by a line.

Field

Description

Data Type

id

Specifies the segment ID.

integer

name

Specifies the segment name.

string

recency

Specifies the lookback window (in days) that Yahoo DSP uses to determine if a pixel fire occurred.

integer

reachCount

Specifies the number of unique users in the segment.

integer

createdAt

Specifies the date that the segment was created.

string

audienceType

Specifies the source of audience:

  • Yahoo

  • 1st Party

  • 3rd Party

string

segmentType

Specifies the segment type:

string

Segments Excluded Object

The Read Line Targeting API returns the segmentsIncluded and segmentsExcluded objects along with other data about line targeting.

The segmentsExcluded object is a read-only object that displays information about the segments excluded from targeting by a line.

Field

Description

Data Type

id

Specifies the segment ID.

integer

name

Specifies the segment name.

string

recency

Specifies the lookback window (in days) that Yahoo DSP uses to determine if a pixel fire occurred.

integer

reachCount

Specifies the number of unique users in the segment.

integer

createdAt

Specifies the date the segment was created.

string

audienceType

Specifies the source of audience:

  • Yahoo

  • 1st Party

  • 3rd Party

string

segmentType

Specifies the segment type:

string

Available Segments Object

The Read Available Segments API returns an array of Available Segment objects.

The Segment Segment object is a read-only object that displays information about a segment available for targeting.

Field

Description

Data Type

id

Specifies the segment ID.

string

name

Specifies the segment name.

string

status

Specifies the status of the segment:

  • ACTIVE

  • INACTIVE

string

segmentType

Specifies the segment type.

string

reachCount

Specifies the number of consumers in the segment.

number

audienceType

Specifies the source of the data:

  • YAHOO - Yahoo/Yahoo segments

  • DMP - Third-party segments

  • ADVERTISER - First-party segments

string

createdBy

Specifies the username of the user account that created the segment.

string

createdAt

Specifies the date that the segment was created.

string

hierarchy

Specifies an array representing the segment hierarchy where the final element in the array stores the top node of the hierarchy.

array

Read Available Segments

Returns filtered list of segments that may be targeted.

GET /traffic/targeting/availablesegments/search?lineId={lineId}&accountId={accountId}query={query}&country_codes={country_codes}&limit={limit}&page={page}&type={type}&minAudienceSize={minAudienceSize}&maxAudienceSize={maxAudienceSize}

All of the accepted parameters are query parameters.

Parameters

Parameter

Description

Data Type

Required

accountId

Specifies the advertiser ID.

integer

Y

query

Specifies a search term. Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string

Y

country_codes

Specifies the country iso3 codes list (comma separated) used to filter out the segments based on their country availability.

string

N

lineId

Specifies the line ID.

integer

N

limit

Specifies the total number of items to return. Default is 50.

integer

N

page

Specifies the page number.

integer

N

type

Specifies the segment type.

string

N

minAudienceSize

Specifies the minimum number of active unique users within a segment.

integer

N

maxAudienceSize

Specifies the maximum number of active unique users within a segment.

integer

N

Example Request

GET  https://dspapi.admanagerplus.yahoo.com/traffic/targeting/availablesegments/search?accountId=507&filterFacts=true&limit=20&lineId=277165&page=1&query=auto&country_codes=USA,GBR&status=Active&type=COMPOSITE%2CLOOKALIKE%2CWEBSITE%2CCONVERSIONRULE%2CCUSTOM%2CEMAIL%2CIPADDRESS%2CSRT%2CMRT%2CEVENTLEVEL%2CGEORETARGET%2CINTEREST%2CMIC%2CFACT

Example Response

{
  "response": [
    {
      "id": 50134447,
      "name": "Cuebiq > Mobile Audience > Retail > Auto Parts/Auto Repair Shoppers > Advance Auto Parts",
      "status": "ACTIVE",
      "hierarchy": [
        {
          "name": "Cuebiq > Mobile Audience > Retail > Auto Parts/Auto Repair Shoppers"
        },
        {
          "name": "Cuebiq > Mobile Audience > Retail"
        },
        {
          "name": "Mobile Audience"
        },
        {
          "name": "Cuebiq"
        },
        {
          "name": "Liveramp Third Party"
        },
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "audienceType": "DMP",
      "segmentType": "FACT",
      "reachCount": 21056761,
      "createdAt": "2017-02-09"
    },
    {
      "id": 50134434,
      "name": "Cuebiq > Mobile Audience > Retail > Auto Parts/Auto Repair Shoppers > O'Reilly Auto Parts",
      "status": "ACTIVE",
      "hierarchy": [
        {
          "name": "Cuebiq > Mobile Audience > Retail > Auto Parts/Auto Repair Shoppers"
        },
        {
          "name": "Cuebiq > Mobile Audience > Retail"
        },
        {
          "name": "Mobile Audience"
        },
        {
          "name": "Cuebiq"
        },
        {
          "name": "Liveramp Third Party"
        },
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "audienceType": "DMP",
      "segmentType": "FACT",
      "reachCount": 16431194,
      "createdAt": "2017-02-09"
    }
  ],
  "errors": null,
  "timeStamp": "2018-04-02T18:02:48Z"
}

Add/Update Segment Targeting

Add or update segment targeting for the specified line.

POST /traffic/lines/{id}/targeting

Parameters

The line ID is specified in the path of the URL. All other parameters are specified in the body of the application/json payload.

Example Request URL

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

Example Request Body (Add)

{
  "segments": {
    "added": [
      {
        "excluded": false,
        "entityId": 20703845
      },
      {
        "excluded": true,
        "entityId": 50348744
      }
    ]
  },
  "types": [
    {
      "name": "SEGMENT",
      "isTargeted": true
    }
  ]
}

Example Request Body (Remove)

{
  "id": 365277,
  "segments": {
    "removed": [
      50348744
    ]
  },
  "types": [
    {
      "name": "SEGMENT",
      "isTargeted": true
    }
  ]
}

Additional Resources