Audiences from your website

Overview

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 Gemini, 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"
          }
      }