Method: accountTypes.accounts.insights.retrieve

Retrieves marketing data insights for a given user list.

This feature is only available to data partners.

Authorization Headers:

This method supports the following optional headers to define how the API authorizes access for the request:

  • login-account: (Optional) The resource name of the account where the Google Account of the credentials is a user. If not set, defaults to the account of the request. Format: accountTypes/{loginAccountType}/accounts/{loginAccountId}
  • linked-account: (Optional) The resource name of the account with an established product link to the login-account. Format: accountTypes/{linkedAccountType}/accounts/{linkedAccountId}

HTTP request

POST https://datamanager.googleapis.com/v1/{parent=accountTypes/*/accounts/*}/insights:retrieve

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The parent account that owns the user list. Format: accountTypes/{accountType}/accounts/{account}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "baseline": {
    object (Baseline)
  },
  "userListId": string
}
Fields
baseline

object (Baseline)

Required. Baseline for the insights requested.
userListId

string

Required. The user list ID for which insights are requested.

Response body

Response message for DM API MarketingDataInsightsService.RetrieveInsights

If successful, the response body contains data with the following structure:

JSON representation 
{
  "marketingDataInsights": [
    {
      object (MarketingDataInsight)
    }
  ]
}
Fields
marketingDataInsights[]

object (MarketingDataInsight)

Contains the insights for the marketing data.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/datamanager

Baseline

Baseline criteria against which insights are compared.

JSON representation 
{

  // Union field baseline can be only one of the following:
  "baselineLocation": {
    object (Location)
  },
  "locationAutoDetectionEnabled": boolean
  // End of list of possible types for union field baseline.
}
Fields
Union field baseline. Baseline location against which insights are compared. baseline can be only one of the following:
baselineLocation

object (Location)

The baseline location of the request. Baseline location is an OR-list of the requested regions.
locationAutoDetectionEnabled

boolean

If set to true, the service will try to automatically detect the baseline location for insights.

Location

The baseline location of the request. Baseline location is on OR-list of ISO 3166-1 alpha-2 region codes of the requested regions.

JSON representation 
{
  "regionCodes": [
    string
  ]
}
Fields
regionCodes[]

string

List of ISO 3166-1 alpha-2 region codes.

MarketingDataInsight

Insights for marketing data.

This feature is only available to data partners.

JSON representation 
{
  "dimension": enum (AudienceInsightsDimension),
  "attributes": [
    {
      object (MarketingDataInsightsAttribute)
    }
  ]
}
Fields
dimension

enum (AudienceInsightsDimension)

The dimension to which the insight belongs.
attributes[]

object (MarketingDataInsightsAttribute)

Insights for values of a given dimension.

AudienceInsightsDimension

Possible dimensions for use in generating insights.

Enums
AUDIENCE_INSIGHTS_DIMENSION_UNSPECIFIED Not specified.
AUDIENCE_INSIGHTS_DIMENSION_UNKNOWN The value is unknown in this version.
AFFINITY_USER_INTEREST An Affinity UserInterest.
IN_MARKET_USER_INTEREST An In-Market UserInterest.
AGE_RANGE An age range.
GENDER A gender.

MarketingDataInsightsAttribute

Insights for a collection of related attributes of the same dimension.

JSON representation 
{
  "userInterestId": string,
  "lift": number,
  "ageRange": enum (AgeRange),
  "gender": enum (Gender)
}
Fields
userInterestId

string (int64 format)

The user interest ID.
lift

number

Measure of lift that the audience has for the attribute value as compared to the baseline. Range [0-1].
ageRange

enum (AgeRange)

Age range of the audience for which the lift is provided.
gender

enum (Gender)

Gender of the audience for which the lift is provided.

AgeRange

The demographic age ranges

Enums
AGE_RANGE_UNSPECIFIED Not specified.
AGE_RANGE_UNKNOWN Unknown.
AGE_RANGE_18_24 Between 18 and 24 years old.
AGE_RANGE_25_34 Between 25 and 34 years old.
AGE_RANGE_35_44 Between 35 and 44 years old.
AGE_RANGE_45_54 Between 45 and 54 years old.
AGE_RANGE_55_64 Between 55 and 64 years old.
AGE_RANGE_65_UP 65 years old and beyond.

Gender

The type of demographic genders (for example, female).

Enums
GENDER_UNSPECIFIED Not specified.
GENDER_UNKNOWN Unknown.
GENDER_MALE Male.
GENDER_FEMALE Female.