Audiences

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

Audience Discovery API

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

list_audiences_taxonomy(body: dict or str, **kwargs) → ApiResponse:

Returns a list of audience categories for a given category path

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

Kwargs:

advertiserId: string (query) The advertiser associated with the advertising account. This parameter is required for the DSP adType, but optional for the SD adType.

nextToken: string (query) Token from a previous request. Use in conjunction with the maxResults parameter to control pagination of the returned array.

maxResults: integer (query) Sets the maximum number of categories in the returned array. Use in conjunction with the nextToken parameter to control pagination. For example, supplying maxResults=20 with a previously returned token will fetch up to the next 20 items. In some cases, fewer items may be returned. Default value : 250

body: dict or str (data) REQUIRED {

“adType”: string Enum [ DSP, SD ]

“categoryPath”:

[

string

]

}

Returns ApiResponse

### Example python

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

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s:%(levelname)s:%(message)s"
)


def list_audiences_taxonomy(data: (str, dict)):
    try:

        result = Audiences(debug=True).list_audiences_taxonomy(
            body=data
        )

        logging.info(result)

    except AdvertisingApiException as error:
        logging.info(error)


if __name__ == '__main__':

    category_path = "Lifestyle" # In-market

    request = \
        {
            "adType": "SD",
            "categoryPath": [
                category_path
            ]
        }

    list_audiences_taxonomy(request)

### Example query_taxonomy.json

{
  "adType": "SD",
  "categoryPath": [
    "In-market"
  ]
}

Download json the file to use

# Result using the request query above

{
    "categoryPath": ["Lifestyle"],
    "categories": [
        {"category": "Automotive Ownership", "audienceCount": 65},
        {"category": "Business & Industry", "audienceCount": 19},
        {"category": "New to Category", "audienceCount": 11},
        {"category": "Entertainment", "audienceCount": 8},
        {"category": "Shoppers", "audienceCount": 4},
        {"category": "Students & Professionals", "audienceCount": 3},
        {"category": "Characteristics", "audienceCount": 2},
        {"category": "Conscious Consumption", "audienceCount": 1},
        {"category": "Family", "audienceCount": 1},
        {"category": "Subscriptions", "audienceCount": 1},
    ],
}

list_audiences(body: dict or str, **kwargs) → ApiResponse:

Returns a list of audience segments for an advertiser. The result set can be filtered by providing an array of Filter objects. Each item in the resulting set will match all specified filters.

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

Kwargs:

advertiserId: string (query) The advertiser associated with the advertising account. This parameter is required for the DSP adType, but optional for the SD adType.

nextToken: string (query) Token from a previous request. Use in conjunction with the maxResults parameter to control pagination of the returned array.

maxResults: integer (query) Sets the maximum number of categories in the returned array. Use in conjunction with the nextToken parameter to control pagination. For example, supplying maxResults=20 with a previously returned token will fetch up to the next 20 items. In some cases, fewer items may be returned. Default value : 10

body: dict or str (data) REQUIRED {

“adType”: string Enum [ DSP, SD ]

“filters”: [

{

“field”: string Field to filter by. Supported enums are ‘audienceName’, ‘category’, ‘categoryPath’ and ‘audienceId’. The ‘category’ enum returns all audiences under a high-level category, whereas the ‘categoryPath’ enum expects a path of nodes in the taxonomy tree and returns audiences attached directly to the node at the specified path.

“values”: [

string

]

}

]

}

Returns ApiResponse

### Example python

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

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s:%(levelname)s:%(message)s"
)


def list_audiences(**kwargs):
    try:

        result = Audiences(debug=True).list_audiences(
            **kwargs
        )

        logging.info(result)
        print (result.payload)

    except AdvertisingApiException as error:
        logging.info(error)


if __name__ == '__main__':

    audience_name = "Automotive Ownership"

    request = \
        {
            "adType": "SD",
            "filters": [
                {
                    "field": "audienceName",
                    "values": [
                        audience_name
                    ]
                }
            ]
        }

    list_audiences(body=request, maxResults=2)

# Result using the request query above

{
    "audiences": [
        {
            "audienceId": "381539216349606208",
            "audienceName": "LS - Vehicle Owners",
            "description": "People who own vehicles",
            "category": "Lifestyle",
            "createDate": "2019-06-27T13:19:12.656Z",
            "updateDate": "2021-03-10T06:52:21Z",
            "status": "Active",
            "forecasts": {
                "inventoryForecasts": {
                    "all": {
                        "dailyReach": {
                            "lowerBoundInclusive": 2000000,
                            "upperBoundExclusive": 2500000,
                        }
                    }
                }
            },
        },
        {
            "audienceId": "423091775444044780",
            "audienceName": "IM - Coche y moto",
            "description": "Personas cuyas actividades de compras\xa0 indican que estan inclinadas a comprar productos de Coche y moto",
            "category": "In-market",
            "createDate": "2013-04-19T00:00:00Z",
            "updateDate": "2017-09-19T23:36:00.964Z",
            "status": "Active",
            "forecasts": {
                "inventoryForecasts": {
                    "all": {
                        "dailyReach": {
                            "lowerBoundInclusive": 1500000,
                            "upperBoundExclusive": 2000000
                        }
                    }
                }
            },
        },
    ],
    "matchCount": 44,
    "nextToken": "RlYDS3X-i8zaLNutSzVIJIQ7RJZ2WYnHyi17DVEHBlZ-skWA-ubGpcNeuoUKas4uKXRen2DYddavk_QtvVRgl8swN6v5KSo86n6tuiy95u4R5OJcmKZ5_7ExV19KnFZIf-aEOnSslt9Kp84HJQjfFffTJRTzf3nIAa61kFPdVuGeW-fEuZvAgdZgowSuW5NhA76bR5wPL1jPcxATKqr4b2dZFYb36r9AYVzpRgEOcI2K6PxECaq4sVDjIztIgHf1BxyLO0ppZcuGFgpnzAKf-l_Bv5zNcWHLqo--"
}

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 20 with a delay of 5 seconds betwwen query

import logging
from ad_api.api import Audiences
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 Audiences(debug=True).list_audiences(**kwargs)

if __name__ == '__main__':

    request = \
        {
            "adType": "SD",
        }

    for page in get_all_categories(maxResults=20,body=request):
        result = page.payload
        audiences = result.get("audiences")
        for audience in audiences:
            logging.info(audience)

### Example query_general.json

{
  "adType": "SD"
}