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:

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.

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, refer to 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.

array

Required

N/A

deviceType

Specifies the device type you want to include in the audience.

Allowed values:

  • ALL

  • DESKTOP

  • MOBILE

string

Required

N/A

expectedSize

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

integer

Optional [2]

Optional

seedAudienceName

A read-only field that specifies the seed audience name.

string

N/A

N/A

seedAudienceType

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 Audience

Read a specific lookalike audience.

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

Parameters

Parameter

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",
    "deviceType": "DESKTOP"
  },
  "errors": null,
  "timeStamp": "2017-12-01T21:41:09Z"
}

Create Audience

Create a new lookalike audience.

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",
  "deviceType": "DESKTOP"
}

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",
    "deviceType": "DESKTOP"
  },
  "errors": null,
  "timeStamp": "2017-12-01T22:30:37Z"
}

Update 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",
    "deviceType": "DESKTOP"
  },
  "errors": null,
  "timeStamp": "2017-12-01T22:26:09Z"
}

Delete 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}&country_codes={country_codes}&page={page}&limit={limit}

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

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

country_codes

query

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

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:

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&country_codes=USA,GBR

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": "SY",
      "name": "Syrian Arab Republic"
    },
    {
      "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"
    }
  ]
}