REST Resource: networks.audienceSegments

  • The AudienceSegment resource represents a specific audience segment.

  • The AudienceSegment resource has name and displayName fields.

  • You can retrieve a specific AudienceSegment object using the get method or a list of them using the list method.

Resource: AudienceSegment

The AudienceSegment resource.

JSON representation 
{
  "name": string,
  "sharedId": string,
  "categoryIds": [
    string
  ],

  // Union field sub_type can be only one of the following:
  "nonRuleBasedFirstPartyAudienceSegment": {
    object (NonRuleBasedFirstPartyAudienceSegment)
  },
  "ruleBasedFirstPartyAudienceSegment": {
    object (RuleBasedFirstPartyAudienceSegment)
  },
  "thirdPartyAudienceSegment": {
    object (ThirdPartyAudienceSegment)
  }
  // End of list of possible types for union field sub_type.
  "displayName": string,
  "description": string,
  "status": enum (AudienceSegmentStatus),
  "size": string,
  "mobileWebSize": string,
  "idfaSize": string,
  "adIdSize": string,
  "ppidSize": string,
  "dataProviderDisplayName": string,
  "segmentType": enum (AudienceSegmentType)
}
Fields
name

string

Identifier. The resource name of the AudienceSegment. Format: networks/{networkCode}/audienceSegments/{audienceSegmentId} The audienceSegmentId is not always numerical and may have one of the following suffixes: - ~direct for directly licensed third-party segments - ~global for globally licensed third-party segments
sharedId

string (int64 format)

Output only. The ID of the AudienceSegment. Up to two resources may share this ID.
categoryIds[]

string (int64 format)

Optional. Unordered list. IDs of the categories that this audience segment belongs to. See segment_categories for additional information about the categories.
Union field sub_type. Based on the type classification, the AudienceSegment has additional information in zero or one of the following sub-types. sub_type can be only one of the following:
nonRuleBasedFirstPartyAudienceSegment

object (NonRuleBasedFirstPartyAudienceSegment)

Optional. An AudienceSegment owned by the publisher network that does not contain a rule. Cookies are usually added to these segments through cookie upload.
ruleBasedFirstPartyAudienceSegment

object (RuleBasedFirstPartyAudienceSegment)

Optional. An AudienceSegment owned by the publisher network that contains a rule.
thirdPartyAudienceSegment

object (ThirdPartyAudienceSegment)

Output only. An AudienceSegment owned by a data provider and licensed to the Ad Manager publisher network.
displayName

string

Required. Display name of the AudienceSegment. The attribute has a maximum length of 255 characters.
description

string

Optional. Description of the AudienceSegment. This has a maximum length of 8192 characters.
status

enum (AudienceSegmentStatus)

Output only. Non-empty default. Status of the AudienceSegment used to determine whether the segment is available for targeting. Defaults to ACTIVE if not set.
size

string (int64 format)

Output only. Number of unique identifiers in the AudienceSegment.
mobileWebSize

string (int64 format)

Output only. Number of unique mobile web identifiers in the AudienceSegment.
idfaSize

string (int64 format)

Output only. Number of unique Identifier for Advertisers (IDFA) identifiers in the AudienceSegment.
adIdSize

string (int64 format)

Output only. Number of unique AdID identifiers in the AudienceSegment.
ppidSize

string (int64 format)

Output only. Number of unique publisher-provided (PPID) identifiers in the AudienceSegment.
dataProviderDisplayName

string

Output only. Display name of the owner data provider. For a first-party audience segment, this is the display name of the publisher network. Otherwise, this is the display name of the entity providing the audience segment.
segmentType

enum (AudienceSegmentType)

Output only. Non-empty default. Type of the AudienceSegment. Every AudienceSegment is either FIRST_PARTY or THIRD_PARTY.

NonRuleBasedFirstPartyAudienceSegment

An AudienceSegment owned by the publisher network that does not contain a rule. Cookies are usually added to these segments through cookie upload.

JSON representation 
{
  "membershipExpirationDays": string
}
Fields
membershipExpirationDays

string (int64 format)

Required. Number of days after which a user's cookie will be removed from the AudienceSegment due to inactivity. The field can be between 1 and 540.

RuleBasedFirstPartyAudienceSegment

An AudienceSegment owned by the publisher network that contains a rule.

JSON representation 
{
  "rule": {
    object (Rule)
  },
  "pageViews": string,
  "recencyDays": string,
  "membershipExpirationDays": string
}
Fields
rule

object (Rule)

Required. The rule definition which determines the eligibility criteria for the AudienceSegment.
pageViews

string (int64 format)

Required. Number of times a user's cookie must match the rule before it's associated with the AudienceSegment. This is used with recencyDays to determine eligibility of the association. This attribute is between 1 and 12.
recencyDays

string (int64 format)

Optional. Number of days within which a user's cookie must match the rule before it's associated with the AudienceSegment. This is used with pageViews to determine eligibility of the association. This attribute is required if pageViews is greater than 1. When set, it can be between 1 and 30.
membershipExpirationDays

string (int64 format)

Required. Number of days after which a user's cookie will be removed from the AudienceSegment due to inactivity. The field can be between 1 and 540.

Rule

Eligibility criteria for a user to be part of an AudienceSegment.

JSON representation 
{
  "inventoryTargeting": {
    object (InventoryTargeting)
  },
  "customTargeting": {
    object (CustomTargeting)
  }
}
Fields
inventoryTargeting

object (InventoryTargeting)

Required. Specification of inventory (i.e. ad units and placements) that are part of the rule of the RuleBasedFirstPartyAudienceSegment.
customTargeting

object (CustomTargeting)

Optional. Specification of custom criteria that are part of the rule of the RuleBasedFirstPartyAudienceSegment. Once specified, the server may return a normalized but equivalent representation of the rule. There are up to 3 levels of custom criteria allowed. See CustomTargeting and its sub-messages for limitations.

ThirdPartyAudienceSegment

An AudienceSegment owned by a data provider and licensed to the Ad Manager publisher network.

JSON representation 
{
  "cost": {
    object (Money)
  },
  "startTime": string,
  "endTime": string,
  "approvalStatus": enum (AudienceSegmentApprovalStatus),
  "licenseType": enum (AudienceSegmentLicenseType)
}
Fields
cost

object (Money)

Output only. The CPM cost for the given segment. This is assigned by the data provider. The CPM cost comes from the active pricing if it exists, otherwise it comes from the latest pricing.
startTime

string (Timestamp format)

Output only. Time which this segment becomes available for use. It is assigned by the data provider.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Output only. Time which this segment ceases to be available. It is assigned by the data provider.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
approvalStatus

enum (AudienceSegmentApprovalStatus)

Output only. Whether the publisher has approved or rejected the segment.
licenseType

enum (AudienceSegmentLicenseType)

Output only. The license type of the external segment.

AudienceSegmentApprovalStatus

Specifies the approval status of a ThirdPartyAudienceSegment.

Enums
AUDIENCE_SEGMENT_APPROVAL_STATUS_UNSPECIFIED Default value. This value is unused.
APPROVED Indicates that this segment is approved and can be targeted.
REJECTED Indicates that this segment is rejected and cannot be targeted.
UNAPPROVED Indicates that this segment is waiting to be approved or rejected. It cannot be targeted.

AudienceSegmentLicenseType

Specifies the license type of a ThirdPartyAudienceSegment.

Enums
AUDIENCE_SEGMENT_LICENSE_TYPE_UNSPECIFIED Default value. This value is unused.
DIRECT Indicates that the license is the result of a direct contract between the data provider and the publisher.
GLOBAL Indicates that the license is the result of an agreement between Google and the data provider, which agrees to license their audience segments to all the publishers and/or advertisers of the Google ecosystem.

AudienceSegmentStatus

Specifies the status of an AudienceSegment.

Enums
AUDIENCE_SEGMENT_STATUS_UNSPECIFIED Default value. This value is unused.
ACTIVE Indicates that this audience segment is available for targeting.
INACTIVE Indicates that this audience segment is not available for targeting.
UNUSED Indicates that this audience segment was deactivated by Google because it is unused.

AudienceSegmentType

Specifies the type of an AudienceSegment.

Enums
AUDIENCE_SEGMENT_TYPE_UNSPECIFIED Default value. This value is unused.
FIRST_PARTY Indicates that the segment is a first party segment created and owned by the publisher.
SHARED Indicates that the segment is a first party segment shared by other clients.
THIRD_PARTY Indicates that the segment is a third party segment licensed by the publisher from data providers. This does not include Google-provided licensed segments.

Methods

batchActivate

 Activates AudienceSegment objects.

batchApprove

 Approves AudienceSegment objects.

batchDeactivate

 Deactivates AudienceSegment objects.

batchPopulate

 Populates AudienceSegment objects.

batchReject

 Rejects AudienceSegment objects.

get

 Retrieves an AudienceSegment object.

list

 Lists AudienceSegment objects.