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
`id`	The unique identifier of the audience.	long	N/A	Required
`advertiserid`	The id of the advertiser that owns the audience.	long	Required	Read-Only
`tagid`	The id of the tag whose events define the audience.	string	Required	Read-Only
`name`	The name of the audience segment. Maximum is 255 characters.	string	Required	Optional
`description`	A description for the segment. Maximum is 255 characters.	string	Optional	Optional
`type`	The custom audience type. Must be set to WEBSITE.	enum	Required	Required
`prefill`	TRUE means including website traffic logged prior to the audience creation. Will default to FALSE if not set.	boolean	Optional	Optional
`rule`	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
`retentionDays`	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
`cnt24h`	Unique user count for the last 24 hours.	long	Read-Only	Read-Only
`cnt30d`	Unique user count for the last 30 days.	long	Read-Only	Read-Only
`status`	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
`advertiserID`	The id of the parent advertiser.	long
`mr`	The maximum number of rows to retrieve. Value should not be greater than 500.	int
`si`	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
`id`	The id of the object to delete.
`status`	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"
          }
      }