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 Native & Search, 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"
          }
      }