Audiences from your website¶
Audiences from your website allow you to define and manage audience segments of people who have visited or have taken certain actions on your website. Once created, these segments will be available for targeting using the TargetingAttribute service.
Important
When you create a custom audience from your website on Yahoo Native make sure you set the default retention period to 90 days. This retains that audience for a period of 90 days until you delete it.
Fields¶
Website audiences have the following fields:
Name |
Description |
Type |
Add |
Update |
---|---|---|---|---|
|
The unique identifier of the audience. |
long |
N/A |
Required |
|
The id of the advertiser that owns the audience. |
long |
Required |
Read-Only |
|
The id of the tag whose events define the audience. |
string |
Required |
Read-Only |
|
The name of the audience segment. Maximum is 255 characters. |
string |
Required |
Optional |
|
A description for the segment. Maximum is 255 characters. |
string |
Optional |
Optional |
|
The custom audience type. Must be set to WEBSITE. |
enum |
Required |
Required |
|
TRUE means including website traffic logged prior to the audience creation. Will default to FALSE if not set. |
boolean |
Optional |
Optional |
|
Rules can be applied on either the referrer URL or on specific parameters sent through the tag. Rules determine whether the user should be added to an audience. A user will be added to the audience within 5 minutes of taking the specified action on your website. See the Managing rules section for more details. |
JSON object |
Required |
Optional |
|
Number of days the user will remain in an audience. Accepts values between 1 and 30 and will default to 15 if not specified. |
int |
Optional |
Optional |
|
Unique user count for the last 24 hours. |
long |
Read-Only |
Read-Only |
|
Unique user count for the last 30 days. |
long |
Read-Only |
Read-Only |
|
The status of the segment. Can be ACTIVE or DELETED, and is set to ACTIVE by default. |
enum |
Optional |
Optional |
Endpoint¶
Resource URI
https://api.gemini.yahoo.com/v3/rest/audience/
Read audience data
Method: To read audience data, you can make a GET call and pass in the following parameters:
Name |
Description |
Type |
---|---|---|
|
The id of the parent advertiser. |
long |
|
The maximum number of rows to retrieve. Value should not be greater than 500. |
int |
|
The start index or the first element to retrieve. |
int |
Example: GET call for a filtered list of audiences:
https://api.gemini.yahoo.com/v3/rest/audience/?advertiserId=11610
The response will be the relevant audiences:
{
"errors": null,
"timestamp": "2015-07-09 4:50:45",
"response": [
{
"type": "WEBSITE",
"id": 20065734,
"name": "Jackets",
"description": "",
"retentionDays": 30,
"cnt30d": 0,
"cnt24h": 0,
"status": "ACTIVE",
"tagId": 401283,
"rule": {
"url": {
"i_contains": "jackets"
}
},
"prefill": "FALSE"
},
{
"type": "WEBSITE",
"id": 20065416,
"name": "Sweaters",
"description": "",
"retentionDays": 30,
"cnt30d": 0,
"cnt24h": 0,
"status": "ACTIVE",
"tagId": 401283,
"rule": {
"url": {
"i_contains": "sweaters"
}
},
"prefill": "FALSE"
}
]
}
Example: GET call for a specific audience:
https://api.gemini.yahoo.com/v3/rest/audience/20065734
The response will be the relevant audience:
{
"errors": null,
"timestamp": "2015-07-09 4:56:20",
"response": {
"type": "WEBSITE",
"id": 20065734,
"name": "Jackets",
"description": "Shoppers for jackets",
"retentionDays": 30,
"cnt30d": 0,
"cnt24h": 0,
"status": "ACTIVE",
"tagId": 401283,
"rule": {
"url": {
"i_contains": "jackets"
}
},
"prefill": "FALSE"
}
}
Update existing audiences
Method: To update one or more existing audiences, make a PUT call with one or more audience objects. Specify the fields to update; note that id and type are the only required parameters, all other fields are optional. The result will be the list of updated objects. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update.
PUT https://api.gemini.yahoo.com/v3/rest/audience
Data passed
{
"retentionDays": 15,
"type": "WEBSITE"
"id": 20065734
}
Example response
{
"errors": null,
"timestamp": "2015-07-09 5:34:17",
"response": {
"type": "WEBSITE",
"id": 20065734,
"advertiserId": 11610,
"name": "Jackets",
"description": null,
"retentionDays": 15,
"status": "ACTIVE",
"tagId": 401283,
"rule": {
"url": {
"i_contains": "jackets"
}
},
"prefill": "FALSE"
}
}
Create a new audience
Method: To create a new audience, make a POST call to the audience endpoint with the required fields. Batch create is supported. The response will be the newly created audience, or a list of multiple new audiences if an array is passed.
For example:
POST https://api.gemini.yahoo.com/v3/rest/audience
Data passed
{
"advertiserId": 11610,
"name": "Jackets",
"tagId": 401283,
"prefill": "FALSE",
"retentionDays": 30,
"rule": {
"url": {
"i_contains": "jackets"
}
},
"type": "WEBSITE"
}
Example response
{
"errors": null,
"timestamp": "2015-07-09 4:39:12",
"response": {
"type": "WEBSITE",
"id": 20065734,
"advertiserId": 11610,
"name": "Jackets",
"description": null,
"retentionDays": 30,
"status": "ACTIVE",
"tagId": 401283,
"rule": {
"url": {
"i_contains": "jackets"
}
},
"prefill": "FALSE"
}
}
Delete an audience
Method: To delete an audience, make a PUT call with the audience object. Batch delete is supported: either a single object or an array can be passed. The following parameters are required:
Name |
Description |
---|---|
|
The id of the object to delete. |
|
The status of the object to be deleted. |
Note
In v2, the DELETE operation is supported for both single and multiple ids.
For example:
PUT https://api.gemini.yahoo.com/v3/rest/audience
DELETE https://api.gemini.yahoo.com/v3/rest/audience/{id}
DELETE https://api.gemini.yahoo.com/v3/rest/audience?id=123&id=1234&...
Data passed
{
"status": DELETED,
"type": "WEBSITE"
"id": 20065734
}
Example response
{
"errors": null,
"timestamp": "2015-07-09 5:34:17",
"response": {
"type": "WEBSITE",
"id": 20065734,
"advertiserId": 11610,
"name": "Jackets",
"description": null,
"retentionDays": 15,
"status": "DELETED",
"tagId": 401283,
"rule": {
"url": {
"i_contains": "jackets"
}
},
"prefill": "FALSE"
}
}