Insights

https://dtrnk0o2zy01c.cloudfront.net/openapi/en-us/dest/Insights_prod_3p.json

class ad_api.api.Insights(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, proxies=None, verify=True, timeout=None, debug=False, access_token=None)

get_insights(audienceId: str, version: int = 1, **kwargs) → ApiResponse

Retrieves the top audiences that overlap with the provided audience.

Requires one of these permissions: [“advertiser_campaign_edit”,”advertiser_campaign_view”]

path audienceId:string | Required. The identifier of an audience.

internal version:int | Optional. The version of the overlapping audiences accept ‘application/vnd.insightsaudiencesoverlap.v’+str(version)+’+json’. Available values : 1, 2 Default: 1

query adType:string | Required. The advertising program. Available values : DSP, SD

query advertiserId:string | Optional. The identifier of the advertiser you’d like to retrieve overlapping audiences for. This parameter is required for the DSP adType, but is optional for the SD adType.

query minimumAudienceSize:number | Optional. If specified, the sizes of all returned overlapping audiences will be at least the provided size. This parameter is supported only for request to return application/vnd.insightsaudiencesoverlap.v1+json.

query maximumAudienceSize:number | Optional. If specified, the sizes of all returned overlapping audiences will be at most the provided size. This parameter is supported only for request to return application/vnd.insightsaudiencesoverlap.v1+json.

query minimumOverlapAffinity:number | Optional. If specified, the affinities of all returned overlapping audiences will be at least the provided affinity.

query maximumOverlapAffinity:number | Optional. If specified, the affinities of all returned overlapping audiences will be at most the provided affinity.

query audienceCategory:array[string] | Optional. f specified, the categories of all returned overlapping audiences will be one of the provided categories.

query maxResults:integer | Optional. Sets the maximum number of overlapping audiences in the response. This parameter is supported only for request to return application/vnd.insightsaudiencesoverlap.v2+json. Default value : 30

query nextToken:string | Optional. TToken to be used to request additional overlapping audiences. If not provided, the top 30 overlapping audiences are returned. Note: subsequent calls must be made using the same parameters as used in previous requests.

Note

This Insights supports 2 different types of content (Accept) so is possible get 2 different responses Just pass an optional parameter (2) as int if you want different option, default is version 1.

### Example getting overlapping categories using keyword arguments

import logging
from ad_api.api import Insights
from ad_api.base import AdvertisingApiException


def get_insights(audience_id: str, ad_type: str, version:int = 1, **kwargs):

    try:

        result = Insights(debug=True).get_insights(
            audienceId=audience_id,
            adType=ad_type,
            version=version,
            **kwargs
        )

        logging.info(result)

    except AdvertisingApiException as error:
        logging.info(error)

if __name__ == '__main__':
    id_audience = "427339506193361161"
    ad_type = "SD"

    get_insights(id_audience, ad_type)
    # With max and min minimumAudienceSize and maximumAudienceSize (version 1)
    # get_insights(id_audience, ad_type, minimumAudienceSize=7, maximumAudienceSize=8)
    # With minimumOverlapAffinity (version 2)
    # get_insights(id_audience, ad_type, 2, minimumOverlapAffinity=10)
    # With maximumOverlapAffinity (version 2)
    # get_insights(id_audience, ad_type, 2, maximumOverlapAffinity=5)
    # With Category Lifestyle (version 2)
    # get_insights(id_audience, ad_type, 2, audienceCategory="Lifestyle")
    # With Category Interest (version 2)
    # get_insights(id_audience, ad_type, 2, audienceCategory="Interest")
    # With a maxResults filter (version 2)
    # get_insights(id_audience, ad_type, 2, maxResults=10)

Note

If you do not provide any filter it will return all the audiences

### Example python retrieving all the audiences with Utils a decorator in sets of 10 with a delay of 5 seconds between query and query

import logging
from ad_api.api import Insights
from ad_api.base import AdvertisingApiException, Utils

@Utils.load_all_categories(throttle_by_seconds=5, next_token_param="nextToken")
def get_all_categories(**kwargs):
    return Insights(debug=True).get_insights(**kwargs)

if __name__ == '__main__':

    id_audience = "427339506193361161"
    ad_type = "SD"

    for page in get_all_categories(audienceId=id_audience, adType=ad_type, version=2, maxResults=10):
        result = page.payload
        overlapping_audiences = result.get("overlappingAudiences")
        for audience in overlapping_audiences:
            logging.info(audience.get("affinity"))
            logging.info(audience.get("audienceMetadata"))