Lookalike Audience

This article describes resources and services that enable you to read, create, and update lookalike audiences.

Overview

A lookalike audience expands the reach of first-party audiences by identifying audience users that are similar to your customers. You can build lookalike audiences based on custom data, Yahoo data and third-party data.

Note

You can only build a lookalike audience for one advertiser at a time, not for an entire seat.

Hierarchy

A Lookalike audience can be defined at the advertiser-level.

  • Advertiser-level audiences are specific to a single advertiser account.

Endpoint

/traffic/audiences/lookalike

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read an existing lookalike audience.
  • Use the POST method to create a new lookalike audience.
  • Use the PUT method to update an existing lookalike audience.

Resources

The Lookalike audience object contains the following fields:

Table 24 Lookalike Audience Fields
Field Description Data Type Create Update
id Specifies the audience ID. integer N/A Required
name Specifies the name of the audience. string Required Optional
status

Specifies the current status of the audience.

Allowed values:

  • ACTIVE: the audience can be targeted.
  • INACTIVE: the audience cannot be targeted.
[1]If not specified when creating the audience, defaults to ACTIVE.
string Optional [1] Optional
accountId

Specifies the advertiser ID.

The audience is tied to a specific advertiser and can only be used in that advertisers’ campaigns. To learn more, see Advertisers.

integer Required Required
seedAudienceId

Specifies the ID of the associated seed audience.

Use Search Seed Audiences to identify relevant segments.

integer Required N/A
countries

Specifies an array of country names.

Use the name field from the Read Supported Countries response.

integer Required N/A
expectedSize

Specifies the expected size for the modeled audience. The audience size is within 10% of this value.

[2]The default is 30 million (users).
integer Optional [2] Optional
seedAudenceName A read-only field that specifies the seed audience name. string N/A N/A
seedAudenceType A read-only field that specifies the seed audience type. string N/A N/A
createdAt A read-only field that specifies the creation timestamp. string N/A N/A

Read Lookalike Audience

Get data for a specific lookalike audience.

GET /traffic/audiences/lookalike/{id}?accountId={accountId}

Parameters

Table 25 Read Lookalike Audience Parameters
Parameters Parameter Type Description Data Type Required
id path Specifies the audience ID. integer Y
accountId query Specifies the advertiser ID. integer Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/50379978?accountId=1356341

Example Response

{
  "response": {
    "id": 50379978,
    "name": "Lookalike",
    "seedAudienceId": 50378341,
    "seedAudienceName": "hp_sets_installer_ie_20171108_59083",
    "seedAudienceType": "EMAIL",
    "createdAt": "2017-11-10",
    "accountId": 1356341,
    "expectedSize": 1000000,
    "countries": [
      "United States"
    ],
    "status": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2017-12-01T21:41:09Z"
}

Update Lookalike Audience

Update an existing lookalike audience.

PUT /traffic/audiences/lookalike/{id}

Partial updates are supported; values of supported fields which are not in the payload will remain unchanged.

Note

After you create a lookalike audience, you can rename it, change its status, or adjust its size. You cannot change the seed audience for a lookalike audience once you create it.

Parameters

The audience id is specified in the endpoint path. All other fields are specified in the body of the application/json payload.

Example Request URL

PUT https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/50379978

Example Request Body

{
  "name": "Update Lookalike",
  "accountId": 1356341,
  "expectedSize": 1500,
  "status": "INACTIVE"
}

Example Response

{
  "response": {
    "id": 50379978,
    "name": "Update Lookalike",
    "seedAudienceId": 50378341,
    "seedAudienceName": "hp_sets_installer_ie_20171108_59083",
    "seedAudienceType": "EMAIL",
    "createdAt": "2017-11-10",
    "accountId": 1356341,
    "expectedSize": 1500,
    "countries": [
      "United States"
    ],
    "status": "INACTIVE"
  },
  "errors": null,
  "timeStamp": "2017-12-01T22:26:09Z"
}

Create Lookalike Audience

Create a new lookalike audiences.

Note

Lookalike audiences take about 24 hours to populate.

POST /traffic/audiences/lookalike

Parameters

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

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike

Example Request Body

{
  "name": "Lookalike",
  "seedAudienceId": 50378341,
  "accountId": 1356341,
  "expectedSize": 1000000,
  "countries": [
    "United States"
  ],
  "status": "ACTIVE"
}

Example Response

{
  "response": {
    "id": 50379978,
    "name": "Lookalike",
    "seedAudienceId": 50378341,
    "seedAudienceName": "hp_sets_installer_ie_20171108_59083",
    "seedAudienceType": "EMAIL",
    "createdAt": "2017-12-01",
    "accountId": 1356341,
    "expectedSize": 1000000,
    "countries": [
      "United States"
    ],
    "status": "ACTIVE"
  },
  "errors": null,
  "timeStamp": "2017-12-01T22:30:37Z"
}

Delete Lookalike Audiences

The DSP Traffic API does not support deletion of lookalike audiences.

Search Seed Audiences

Search for seed audiences available to the specified account.

GET /traffic/audiences/lookalike/search?accountId={accountId}&segment={segment}&access={access}&query={query}&page={page}&limit={limit}

Parameters

Table 26 Search Seed Audience Parameters
Parameter Parameter Type Description Data Type Required
accountId query Specifies the advertiser ID. integer Y
segment query

Specifies the seed audience type.

Allowed values:

string Y
access query

Specifies the segment access control.

  • OWNED: Specifies audiences owned by advertiser.
  • DIRECT_SHARED: Specifies audiences that have been explicitly shared with an advertiser. Does not include GLOBAL segments and segments shared to seat.
  • SHARED: Specifies GLOBAL segments, direct shared segments, or segments owned or shared to seat. These segments are visible to every advertiser in any seat.
  • ALL
[3]Default is ALL.
string N [#]
query query

Specifies the search term.

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

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Default value is 20. Maximum allowed value is 100. integer N

Response Fields

The search response will contain a list of matching segments which can be used to create a Lookalike audience. Note the following fields of interest:

Table 27 Search Seed Audience Response Fields
Name Description
id Unique ID of the segment. This value will be used as seedAudienceId when creating a new Lookalike audience.
name Segment name.
status Current status of the segment.
segmentType Seed audience type.
reachCount Number of unique users in this segment.

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/audiences/lookalike/search?accountId=1356341&access=OWNED&segment=WEBSITE

Example Response

{
  "response": [
    {
      "id": 50387897,
      "name": "HK_Property_Men_All",
      "status": "ACTIVE",
      "segmentType": "WEBSITE",
      "reachCount": 223437
    },
    {
      "id": 50387894,
      "name": "HK_Property_Men_Fashion & Grooming",
      "status": "ACTIVE",
      "segmentType": "WEBSITE",
      "reachCount": 34
    },
    {
      "id": 50387893,
      "name": "HK_Property_Men_Auto",
      "status": "ACTIVE",
      "segmentType": "WEBSITE",
      "reachCount": 10933
    }
  ],
  "errors": null,
  "timeStamp": "2017-12-01T22:50:36Z"
}

Read Supported Countries

Get a list of supported countries.

GET /traffic/audiences/lookalike/supported_countries

Example Response

{
  "supportedCountries": [
    {
      "isoCode": "AF",
      "name": "Afghanistan"
    },
    {
      "isoCode": "AX",
      "name": "Aland Islands"
    },
    {
      "isoCode": "AL",
      "name": "Albania"
    },
    {
      "isoCode": "DZ",
      "name": "Algeria"
    },
    {
      "isoCode": "AS",
      "name": "American Samoa"
    },
    {
      "isoCode": "AD",
      "name": "Andorra"
    },
    {
      "isoCode": "AO",
      "name": "Angola"
    },
    {
      "isoCode": "AI",
      "name": "Anguilla"
    },
    {
      "isoCode": "AQ",
      "name": "Antarctica"
    },
    {
      "isoCode": "AG",
      "name": "Antigua and Barbuda"
    },
    {
      "isoCode": "AR",
      "name": "Argentina"
    },
    {
      "isoCode": "AM",
      "name": "Armenia"
    },
    {
      "isoCode": "AW",
      "name": "Aruba"
    },
    {
      "isoCode": "AU",
      "name": "Australia"
    },
    {
      "isoCode": "AT",
      "name": "Austria"
    },
    {
      "isoCode": "AZ",
      "name": "Azerbaijan"
    },
    {
      "isoCode": "BS",
      "name": "Bahamas"
    },
    {
      "isoCode": "BH",
      "name": "Bahrain"
    },
    {
      "isoCode": "BD",
      "name": "Bangladesh"
    },
    {
      "isoCode": "BB",
      "name": "Barbados"
    },
    {
      "isoCode": "BY",
      "name": "Belarus"
    },
    {
      "isoCode": "BE",
      "name": "Belgium"
    },
    {
      "isoCode": "BZ",
      "name": "Belize"
    },
    {
      "isoCode": "BJ",
      "name": "Benin"
    },
    {
      "isoCode": "BM",
      "name": "Bermuda"
    },
    {
      "isoCode": "BT",
      "name": "Bhutan"
    },
    {
      "isoCode": "BO",
      "name": "Bolivia"
    },
    {
      "isoCode": "BA",
      "name": "Bosnia and Herzegovina"
    },
    {
      "isoCode": "BW",
      "name": "Botswana"
    },
    {
      "isoCode": "BR",
      "name": "Brazil"
    },
    {
      "isoCode": "IO",
      "name": "British Indian Ocean Territory"
    },
    {
      "isoCode": "VG",
      "name": "British Virgin Islands"
    },
    {
      "isoCode": "BN",
      "name": "Brunei Darussalam"
    },
    {
      "isoCode": "BG",
      "name": "Bulgaria"
    },
    {
      "isoCode": "BF",
      "name": "Burkina Faso"
    },
    {
      "isoCode": "KH",
      "name": "Cambodia"
    },
    {
      "isoCode": "CM",
      "name": "Cameroon"
    },
    {
      "isoCode": "CA",
      "name": "Canada"
    },
    {
      "isoCode": "CV",
      "name": "Cape Verde"
    },
    {
      "isoCode": "KY",
      "name": "Cayman Islands"
    },
    {
      "isoCode": "CF",
      "name": "Central African Republic"
    },
    {
      "isoCode": "TD",
      "name": "Chad"
    },
    {
      "isoCode": "CL",
      "name": "Chile"
    },
    {
      "isoCode": "CN",
      "name": "China"
    },
    {
      "isoCode": "CO",
      "name": "Colombia"
    },
    {
      "isoCode": "KM",
      "name": "Comoros"
    },
    {
      "isoCode": "CG",
      "name": "Congo"
    },
    {
      "isoCode": "CD",
      "name": "Congo - The Democratic Rep Of"
    },
    {
      "isoCode": "CK",
      "name": "Cook Islands"
    },
    {
      "isoCode": "CR",
      "name": "Costa Rica"
    },
    {
      "isoCode": "HR",
      "name": "Croatia (Local Name - Hrvatska)"
    },
    {
      "isoCode": "CY",
      "name": "Cyprus"
    },
    {
      "isoCode": "CZ",
      "name": "Czech Republic"
    },
    {
      "isoCode": "DK",
      "name": "Denmark"
    },
    {
      "isoCode": "DJ",
      "name": "Djibouti"
    },
    {
      "isoCode": "DM",
      "name": "Dominica"
    },
    {
      "isoCode": "DO",
      "name": "Dominican Republic"
    },
    {
      "isoCode": "EC",
      "name": "Ecuador"
    },
    {
      "isoCode": "EG",
      "name": "Egypt"
    },
    {
      "isoCode": "SV",
      "name": "El Salvador"
    },
    {
      "isoCode": "GQ",
      "name": "Equatorial Guinea"
    },
    {
      "isoCode": "ER",
      "name": "Eritrea"
    },
    {
      "isoCode": "EE",
      "name": "Estonia"
    },
    {
      "isoCode": "ET",
      "name": "Ethiopia"
    },
    {
      "isoCode": "FK",
      "name": "Falkland Islands (Malvinas)"
    },
    {
      "isoCode": "FO",
      "name": "Faroe Islands"
    },
    {
      "isoCode": "FJ",
      "name": "Fiji"
    },
    {
      "isoCode": "FI",
      "name": "Finland"
    },
    {
      "isoCode": "FR",
      "name": "France"
    },
    {
      "isoCode": "GF",
      "name": "French Guiana"
    },
    {
      "isoCode": "PF",
      "name": "French Polynesia"
    },
    {
      "isoCode": "GA",
      "name": "Gabon"
    },
    {
      "isoCode": "GM",
      "name": "Gambia"
    },
    {
      "isoCode": "GE",
      "name": "Georgia"
    },
    {
      "isoCode": "DE",
      "name": "Germany"
    },
    {
      "isoCode": "GH",
      "name": "Ghana"
    },
    {
      "isoCode": "GI",
      "name": "Gibraltar"
    },
    {
      "isoCode": "GR",
      "name": "Greece"
    },
    {
      "isoCode": "GL",
      "name": "Greenland"
    },
    {
      "isoCode": "GD",
      "name": "Grenada"
    },
    {
      "isoCode": "GP",
      "name": "Guadeloupe"
    },
    {
      "isoCode": "GU",
      "name": "Guam"
    },
    {
      "isoCode": "GT",
      "name": "Guatemala"
    },
    {
      "isoCode": "GN",
      "name": "Guinea"
    },
    {
      "isoCode": "GW",
      "name": "Guinea-Bissau"
    },
    {
      "isoCode": "GY",
      "name": "Guyana"
    },
    {
      "isoCode": "HT",
      "name": "Haiti"
    },
    {
      "isoCode": "VA",
      "name": "Holy See (Vatican City State)"
    },
    {
      "isoCode": "HN",
      "name": "Honduras"
    },
    {
      "isoCode": "HK",
      "name": "Hong Kong"
    },
    {
      "isoCode": "HU",
      "name": "Hungary"
    },
    {
      "isoCode": "IS",
      "name": "Iceland"
    },
    {
      "isoCode": "IN",
      "name": "India"
    },
    {
      "isoCode": "ID",
      "name": "Indonesia"
    },
    {
      "isoCode": "IQ",
      "name": "Iraq"
    },
    {
      "isoCode": "IE",
      "name": "Ireland"
    },
    {
      "isoCode": "IL",
      "name": "Israel"
    },
    {
      "isoCode": "IT",
      "name": "Italy"
    },
    {
      "isoCode": "JM",
      "name": "Jamaica"
    },
    {
      "isoCode": "JP",
      "name": "Japan"
    },
    {
      "isoCode": "JO",
      "name": "Jordan"
    },
    {
      "isoCode": "KZ",
      "name": "Kazakhstan"
    },
    {
      "isoCode": "KE",
      "name": "Kenya"
    },
    {
      "isoCode": "KI",
      "name": "Kiribati"
    },
    {
      "isoCode": "KR",
      "name": "Korea - South"
    },
    {
      "isoCode": "KW",
      "name": "Kuwait"
    },
    {
      "isoCode": "KG",
      "name": "Kyrgyzstan"
    },
    {
      "isoCode": "LA",
      "name": "Lao Peoples Democratic Republic"
    },
    {
      "isoCode": "LV",
      "name": "Latvia"
    },
    {
      "isoCode": "LB",
      "name": "Lebanon"
    },
    {
      "isoCode": "LS",
      "name": "Lesotho"
    },
    {
      "isoCode": "LR",
      "name": "Liberia"
    },
    {
      "isoCode": "LY",
      "name": "Libyan Arab Jamahiriya"
    },
    {
      "isoCode": "LI",
      "name": "Liechtenstein"
    },
    {
      "isoCode": "LT",
      "name": "Lithuania"
    },
    {
      "isoCode": "LU",
      "name": "Luxembourg"
    },
    {
      "isoCode": "MO",
      "name": "Macau"
    },
    {
      "isoCode": "MK",
      "name": "Macedonia - The Frm Yugoslav Rep Of"
    },
    {
      "isoCode": "MG",
      "name": "Madagascar"
    },
    {
      "isoCode": "MW",
      "name": "Malawi"
    },
    {
      "isoCode": "MY",
      "name": "Malaysia"
    },
    {
      "isoCode": "MV",
      "name": "Maldives"
    },
    {
      "isoCode": "ML",
      "name": "Mali"
    },
    {
      "isoCode": "MT",
      "name": "Malta"
    },
    {
      "isoCode": "MH",
      "name": "Marshall Islands"
    },
    {
      "isoCode": "MQ",
      "name": "Martinique"
    },
    {
      "isoCode": "MR",
      "name": "Mauritania"
    },
    {
      "isoCode": "MU",
      "name": "Mauritius"
    },
    {
      "isoCode": "YT",
      "name": "Mayotte"
    },
    {
      "isoCode": "MX",
      "name": "Mexico"
    },
    {
      "isoCode": "FM",
      "name": "Micronesia - Federated States Of"
    },
    {
      "isoCode": "MD",
      "name": "Moldova - Republic Of"
    },
    {
      "isoCode": "MC",
      "name": "Monaco"
    },
    {
      "isoCode": "MN",
      "name": "Mongolia"
    },
    {
      "isoCode": "ME",
      "name": "Montenegro"
    },
    {
      "isoCode": "MS",
      "name": "Montserrat"
    },
    {
      "isoCode": "MA",
      "name": "Morocco"
    },
    {
      "isoCode": "MZ",
      "name": "Mozambique"
    },
    {
      "isoCode": "MM",
      "name": "Myanmar"
    },
    {
      "isoCode": "NA",
      "name": "Namibia"
    },
    {
      "isoCode": "NP",
      "name": "Nepal"
    },
    {
      "isoCode": "NL",
      "name": "Netherlands"
    },
    {
      "isoCode": "NC",
      "name": "New Caledonia"
    },
    {
      "isoCode": "NZ",
      "name": "New Zealand"
    },
    {
      "isoCode": "NI",
      "name": "Nicaragua"
    },
    {
      "isoCode": "NE",
      "name": "Niger"
    },
    {
      "isoCode": "NG",
      "name": "Nigeria"
    },
    {
      "isoCode": "MP",
      "name": "Northern Mariana Islands"
    },
    {
      "isoCode": "NO",
      "name": "Norway"
    },
    {
      "isoCode": "OM",
      "name": "Oman"
    },
    {
      "isoCode": "PK",
      "name": "Pakistan"
    },
    {
      "isoCode": "PW",
      "name": "Palau"
    },
    {
      "isoCode": "PS",
      "name": "Palestinian Territories"
    },
    {
      "isoCode": "PA",
      "name": "Panama"
    },
    {
      "isoCode": "PG",
      "name": "Papua New Guinea"
    },
    {
      "isoCode": "PY",
      "name": "Paraguay"
    },
    {
      "isoCode": "PE",
      "name": "Peru"
    },
    {
      "isoCode": "PH",
      "name": "Philippines"
    },
    {
      "isoCode": "PL",
      "name": "Poland"
    },
    {
      "isoCode": "PT",
      "name": "Portugal"
    },
    {
      "isoCode": "PR",
      "name": "Puerto Rico"
    },
    {
      "isoCode": "QA",
      "name": "Qatar"
    },
    {
      "isoCode": "RE",
      "name": "Reunion"
    },
    {
      "isoCode": "RO",
      "name": "Romania"
    },
    {
      "isoCode": "RU",
      "name": "Russian Federation"
    },
    {
      "isoCode": "RW",
      "name": "Rwanda"
    },
    {
      "isoCode": "KN",
      "name": "Saint Kitts and Nevis"
    },
    {
      "isoCode": "LC",
      "name": "Saint Lucia"
    },
    {
      "isoCode": "MF",
      "name": "Saint Martin"
    },
    {
      "isoCode": "VC",
      "name": "Saint Vincent and the Grenadines"
    },
    {
      "isoCode": "WS",
      "name": "Samoa"
    },
    {
      "isoCode": "SM",
      "name": "San Marino"
    },
    {
      "isoCode": "ST",
      "name": "Sao Tome and Principe"
    },
    {
      "isoCode": "SA",
      "name": "Saudi Arabia"
    },
    {
      "isoCode": "SN",
      "name": "Senegal"
    },
    {
      "isoCode": "RS",
      "name": "Serbia"
    },
    {
      "isoCode": "SC",
      "name": "Seychelles"
    },
    {
      "isoCode": "SL",
      "name": "Sierra Leone"
    },
    {
      "isoCode": "SG",
      "name": "Singapore"
    },
    {
      "isoCode": "SX",
      "name": "Sint Maarten"
    },
    {
      "isoCode": "SK",
      "name": "Slovakia (Slovak Republic)"
    },
    {
      "isoCode": "SI",
      "name": "Slovenia"
    },
    {
      "isoCode": "SB",
      "name": "Solomon Islands"
    },
    {
      "isoCode": "SO",
      "name": "Somalia"
    },
    {
      "isoCode": "ZA",
      "name": "South Africa"
    },
    {
      "isoCode": "ES",
      "name": "Spain"
    },
    {
      "isoCode": "LK",
      "name": "Sri Lanka"
    },
    {
      "isoCode": "SH",
      "name": "St. Helena"
    },
    {
      "isoCode": "SR",
      "name": "Suriname"
    },
    {
      "isoCode": "SZ",
      "name": "Swaziland"
    },
    {
      "isoCode": "SE",
      "name": "Sweden"
    },
    {
      "isoCode": "CH",
      "name": "Switzerland"
    },
    {
      "isoCode": "TW",
      "name": "Taiwan - Province Of China"
    },
    {
      "isoCode": "TJ",
      "name": "Tajikistan"
    },
    {
      "isoCode": "TZ",
      "name": "Tanzania - United Republic Of"
    },
    {
      "isoCode": "TH",
      "name": "Thailand"
    },
    {
      "isoCode": "TL",
      "name": "Timor-Leste"
    },
    {
      "isoCode": "TG",
      "name": "Togo"
    },
    {
      "isoCode": "TO",
      "name": "Tonga"
    },
    {
      "isoCode": "TT",
      "name": "Trinidad and Tobago"
    },
    {
      "isoCode": "TN",
      "name": "Tunisia"
    },
    {
      "isoCode": "TR",
      "name": "Turkey"
    },
    {
      "isoCode": "TM",
      "name": "Turkmenistan"
    },
    {
      "isoCode": "TC",
      "name": "Turks and Caicos Islands"
    },
    {
      "isoCode": "TV",
      "name": "Tuvalu"
    },
    {
      "isoCode": "VI",
      "name": "US Virgin Islands"
    },
    {
      "isoCode": "UG",
      "name": "Uganda"
    },
    {
      "isoCode": "UA",
      "name": "Ukraine"
    },
    {
      "isoCode": "AE",
      "name": "United Arab Emirates"
    },
    {
      "isoCode": "UK",
      "name": "United Kingdom"
    },
    {
      "isoCode": "US",
      "name": "United States"
    },
    {
      "isoCode": "UY",
      "name": "Uruguay"
    },
    {
      "isoCode": "UM",
      "name": "Us Minor Outlying Islands"
    },
    {
      "isoCode": "UZ",
      "name": "Uzbekistan"
    },
    {
      "isoCode": "VU",
      "name": "Vanuatu"
    },
    {
      "isoCode": "VE",
      "name": "Venezuela"
    },
    {
      "isoCode": "VN",
      "name": "Viet Nam"
    },
    {
      "isoCode": "YE",
      "name": "Yemen"
    },
    {
      "isoCode": "ZM",
      "name": "Zambia"
    },
    {
      "isoCode": "ZW",
      "name": "Zimbabwe"
    }
  ]
}