Segment Targeting

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

Overview

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

The Oath Ad Platforms DSP supports SEGMENT targeting for lines serving display, video, and native ads. Native lines can target audiences but not beacons.

Endpoints

The Oath Ad Platforms DSP API provides endpoints for reading the segments that can be targeted by a line and for including or excluding those segments in line targeting.

Read Segments

The Oath Ad Platforms DSP API provides two endpoints for reading the segments available for targeting by a line:

GET /traffic/targeting/segments
GET /traffic/targeting/availablesegments

Read Targeted Segments

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

GET     /traffic/lines/{id}/targeting

To learn more, see Read Line Targeting.

Target Segments

The Oath Ad Platforms 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, see About Targeting.

Resources

The Oath Ad Platforms DSP API provides several resources for managing the targeting of segments: targeting, segmentsIncluded, segmentsExcluded, and Available Segments objects.

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 different targeting types including BEACONS, EXCHANGES, and SITE_LISTS. To target segments, you need only be concerned with the following SEGMENT targeting type-specific fields:

Table 144 Targeting Object Fields
Field Description Data Type
segments

Specifies an array of segments to include in or exclude from line targeting.

To learn more, see Segments Object.

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

array
segmentsIncluded A read-only array that shows the segments included in targeting. To learn more, see Segments Included Object. array
segmentsExcluded A read-only array that shows the segments excluded from targeting. To learn more, see Segments Excluded Object. array
beaconsIncluded A read-only array that shows the beacons included in targeting. To learn more, see Beacons Included Object. array
beaconsExcluded A read-only array that shows the beacons excluded from targeting. To learn more, see Beacons Excluded Object. array

Note

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

Segments Object

The segments payload object enables you to Add/Update Segment Targets, Update Segment Targets, Remove Segment Targets, or Clear All Segment Targets targeted by a line.

Table 145 Segments Object
Field Description Data Type
id Specifies the line ID. integer
types Specifies the targeting types to enable or modify. To learn more, see Targeting Types. object
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, see Add/Update Segment Targets.

array
edit

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, see Update Segment Targets.

array
removed

An array of segment IDs to be removed from targeting.

For an example, see Remove Segment Targets.

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, see Clear All Segment Targets.

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.

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.

Table 146 Segments Excluded Object Fields
Field Description Data Type
id Specifies the segment ID. integer
name Specifies the segment name. string
recency Specifies the lookback window (in days) that Oath Ad Platforms 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.

Table 147 Available Segments Fields
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
type

Specifies the segment type.

string
peopleCount Specifies the number of consumers in the segment. number
poweredBy

Specifies the source of the data:

  • 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

Data Providers Object

The Read Data Providers API returns an array of Data Provider objects.

The Data Provider object is a read-only object that displays information about segment data providers.

Table 148 Available Segments Fields
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
hierarchy Specifies an array representing the segment hierarchy where the final element in the array stores the top node of the hierarchy. array
poweredBy

Specifies the source of the data:

  • Yahoo
  • DMP
  • Advertiser
string
type

Specifies the segment type.

string
peopleCount Specifies the number of consumers in the segment. number
createdBy Specifies the username of the user account that created the segment. string
createdAt Specifies the date that the segment was created. string

Read Segments

To retrieve a filtered list of segments available for targeting, make a GET call with the supported query parameters.

GET /traffic/targeting/segments?lineId={lineId}&query={query}&limit={limit}&page={page}

Parameters

The resource takes the following parameters:

Table 149 Read Segments Parameters
Parameter Parameter Type Description Data Type Required?
lineId query Specifies the line ID. integer Y
query query Specifies a search term. Use URL encoding conventions (i.e. a space should be replaced with a + or %20). string Y
limit query Specifies the total number of items to return. Default is 50. integer N
page query Specifies the page number. integer N

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/segments?lineId=365277&limit=2&query=test

Example Response

{
  "response": [
    {
      "id": 50190959,
      "name": "product test - saga test",
      "segmentType": "EVENTLEVEL",
      "reachCount": 504024
    },
    {
      "id": 50348744,
      "name": "FlyWheel Studio Test",
      "segmentType": "COMPOSITE",
      "reachCount": 605620290
    }
  ],
  "errors": null,
  "timeStamp": "2018-01-05T20:04:22Z"
}

Read Available Segments

Returns filtered list of segments that may be targeted.

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

Parameters

The resource takes the following parameters:

Table 150 Read Available Segments Parameters
Parameter Parameter Type Description Data Type Required?
lineId query Specifies the line ID. integer Y
accountId query Specifies the advertiser account ID. integer Y
query query Specifies a search term. Use URL encoding conventions (i.e. a space should be replaced with a + or %20). string Y
limit query Specifies the total number of items to return. Default is 50. integer N
page query Specifies the page number. integer N
type query

Specifies the segment type.

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

string N
dataProviderId query

Specifies comma-separated list of fact IDs for third-party (DMP) taxonomies.

Use the Read Data Providers API to retrieve data provider IDs.

integer N
minAudienceSize query Specifies the minimum number of active unique users within a segment. integer N
maxAudienceSize query 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&status=Active&type=COMPOSITE%2CLOOKALIKE%2CWEBSITE%2CCONVERSIONRULE%2CCUSTOM%2CEMAIL%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"
        }
      ],
      "poweredBy": "DMP",
      "type": "FACT",
      "peopleCount": 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"
        }
      ],
      "poweredBy": "DMP",
      "type": "FACT",
      "peopleCount": 16431194,
      "createdAt": "2017-02-09"
    }
  ],
  "errors": null,
  "timeStamp": "2018-04-02T18:02:48Z"
}

Read Data Providers

Returns an array of segments with information about the data providers.

GET /traffic/targeting/availablesegments/dataproviders

Parameters

The resource takes no parameters.

Example Request

https://dspapi.admanagerplus.yahoo.com/traffic/targeting/availablesegments/dataproviders

Example Response

The response returns an array of Data Provider objects including the data provider ID. To learn more, see Data Providers Object.

Response: {
  "response": [
    {
      "id": 50000037,
      "name": "321auto",
      "status": "ACTIVE",
      "hierarchy": [
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "poweredBy": "DMP",
      "type": "FACT",
      "peopleCount": 11738,
      "createdAt": "2016-01-14"
    },
    {
      "id": 20116507,
      "name": "Nielsen Catalina Solutions (NCS)",
      "status": "ACTIVE",
      "createdBy": "DataX",
      "hierarchy": [
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "poweredBy": "DMP",
      "type": "FACT",
      "peopleCount": 77189204,
      "createdAt": "2014-06-11"
    },
    {
      "id": 20699203,
      "name": "NinthDecimal",
      "status": "ACTIVE",
      "createdBy": "DataX",
      "hierarchy": [
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "poweredBy": "DMP",
      "type": "FACT",
      "peopleCount": 503740720,
      "createdAt": "2016-04-06"
    },
    {
      "id": 50000048,
      "name": "Prod Test Provider",
      "status": "ACTIVE",
      "hierarchy": [
        {
          "name": "3rd Party Data"
        },
        {
          "name": "All"
        }
      ],
      "poweredBy": "DMP",
      "type": "FACT",
      "peopleCount": 0,
      "createdAt": "2016-01-14"
    }
  ],
  "errors": null,
  "timeStamp": "2018-04-03T18:26:34Z"
}

Add/Update Segment Targets

Adds or updates segment targets for the specified line.

POST /traffic/lines/{id}/targeting

The targeting type and all changes are specified in the body of the application/json payload.

The segments payload object enables you to create or update targeted segments (audiences).

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.

Table 151 Add Segment Target Parameters
Parameter Parameter Type Description Data Type Required?
id path Specifies the line ID. integer Y
types body Specifies the targeting types to enable or modify. To learn more, see Targeting Types. object Y
added body

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

  • entityId - ID of the Segment to be added.
  • excluded - Indicates if the added IDs are to be excluded or included. true - exclude from targeting; false - include in targeting.
array Y

Example Requests

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

POST traffic/lines/365277/targeting/

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

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

Update Segment Targets

Updates the segments targeted by the specified line.

POST/traffic/lines/{id}/targeting

The segments payload object enables you to create or update the segments targeted by a line.

Parameters

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

Table 152 Update Segment Targets Parameters
Parameter Parameter Type Description Data Type Required?
id path Specifies the line ID. integer Y
types body Specifies the targeting types to enable or modify. To learn more, see Targeting Types. object Y
edit body

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.
array N

Remove Segment Targets

Removes the segments targeted by the specified line.

POST/traffic/lines/{id}/targeting

The segments payload object enables you to create or update the segments targeted by a line.

Parameters

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

Parameter Parameter Type Description Data Type Required?
id path Specifies the line ID. integer Y
types body Specifies the targeting types to enable or modify. To learn more, see Targeting Types. object Y
removed body An array of segment IDs to be removed from targeting. array N

Example: Segments (Remove)

An example of a payload that removes new target segments to a line:

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

Clear All Segment Targets

Removes the segments targeted by the specified line.

POST/traffic/lines/{id}/targeting

The segments payload object enables you to create or update the segments targeted by a line.

Parameters

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

Table 153 Clear All Segment Targets Parameters
Parameter Parameter Type Description Data Type Required?
id path Specifies the line ID. integer Y
types body Specifies the targeting types to enable or modify. To learn more, see Targeting Types. object Y
clearAll body

Indicates if all existing segments should be removed.

  • If true, remove all targeted segments.
  • If false (the default value), do not remove any targeted Segments.
boolean N