- 18 Minutes to read
Lookalike Audiences
- 18 Minutes to read
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 |
---|---|---|---|---|
| Specifies the audience ID. |
| N/A | Required |
| Specifies the name of the audience. |
| Required | Optional |
| Specifies the current status of the audience. Allowed values:
If not specified when creating the audience, defaults to |
| Optional [1] | Optional |
| 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. |
| Required | Required |
| Specifies the ID of the associated seed audience. Use Search Seed Audiences to identify relevant segments. |
| Required | N/A |
| Specifies an array of country names. Use the |
| Required | N/A |
| Specifies the device type you want to include in the audience. Allowed values:
|
| Required | N/A |
| Specifies the expected size for the modeled audience. The audience size is within 10% of this value. The default is 30 million (users). |
| Optional [2] | Optional |
| A read-only field that specifies the seed audience name. |
| N/A | N/A |
| A read-only field that specifies the seed audience type. |
| N/A | N/A |
| A read-only field that specifies the creation timestamp. |
| 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 |
---|---|---|---|---|
| path | Specifies the audience ID. |
| Y |
| query | Specifies the advertiser ID. |
| 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 |
---|---|---|---|---|
| query | Specifies the advertiser ID. |
| Y |
| query | Specifies the seed audience type. Allowed values:
|
| Y |
| query | Specifies the segment access control.
Default is |
| N |
| query | Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
| N |
| query | Specifies the country iso3 codes list (comma separated) used to filter out the segments based on their country availability. |
| N |
| query | Specifies the page number. |
| N |
| query | Specifies the total number of items to return. Default value is |
| 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 |
---|---|
| Unique ID of the segment. This value will be used as |
| Segment name. |
| Current status of the segment. |
| Seed audience type. |
| 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"
}
]
}