Retrieves one or more audiences or superaudiences.

Request

GET /audiences?page=Page Number&page_size=Items Per Page

Request query string parameters:

Pass the following optional request query string parameters:

Name	Description
page=Page Number	Filter the response by a specific page. Replace this variable with the desired page. Use the navigation links within the @links object to navigate between pages. Default Value: 1
page_size=Items Per Page	Sets the number of audience configurations that may be included on each page. The number of items per page determines the number of pages that may be returned. The maximum page size is 40. Default value: 40

Response

A successful request returns a 200 OK response that contains the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to the requested endpoint.
@type	String	Returns Collection.
items	List of dictionaries	Contains a list of audience configurations.
total_items	Integer	Indicates the total number of audience configurations.

items List

The items list describes each audience configuration via the following properties:

Name	Data Type	Description
@id	String	Indicates the relative path to an endpoint that returns this audience or superaudience.
@type	String	Returns Audience.
country_codes	List of string values	Audience only Indicates the set of countries associated with this audience. Each value identifies a country by its two character country code (ISO 3166). View a list of country codes.
created	String	Indicates the timestamp (UTC) at which the audience or superaudience was created. Syntax (ISO 8601): YYYY-MM-DDThh:mm:ss.sssZ
desc	String	Indicates the name of the audience or superaudience.
devices	List of string values	Audience only Indicates the set of devices associated with this audience. Each value identifies a device by its name or description. Each value in this List will be compared against the value defined for the repl.cbdevice playback URL parameter.
dma_codes	List of string values	Audience only Indicates the set of designated market areas (DMA) associated with this audience. Each value identifies a United States DMS by its ID. Request Nielsen DMA data.
external_id	String	Indicates the external ID associated with this audience or superaudience.
id	String	Identifies this audience or superaudience by its system-defined ID.
ip_networks	List of string values	Audience only Indicates the set of IP addresses or subnets associated with this audience. Each value identifies either an IP address or IP network.
match_type	String	Determines the set of criteria that will be required to qualify a viewer for this audience or superaudience. Valid values are: ALL	ANY	NONE Learn more.
owner	String	Indicates the system-defined ID for the user that owns this audience or superaudience.
sub_audiences	List of string values	Superaudience only Indicates the set of audiences associated with this superaudience. Each value identifies an audience by its system-defined ID. Learn more.
type	String	Indicates whether this configuration is an audience or a superaudience. Valid values are: Single	Multiple Learn more.
zip_codes	List of string values	Audience only Indicates the set of United States zip codes associated with this audience. Each value identifies a zip code.

Sample Request/Response

The code below (Python 3) shows how to retrieve multiple audiences.

This code imports names from the api_auth module for V4 APIs (see below).

import json, requests
from api_auth import APICredentials, APIParams

class Audience:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        self._get_multiple_audiences()

    def _get_multiple_audiences(self):
        url = "{}{}".format(self.host, "/api/v4/audiences")

        headers = {'Content-Type': 'application/json'}

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({}), headers=headers
        )

        print(response.json())

Audience().run()

Response:

{
	'@id': '/api/v4/audiences',
	'@type': 'Collection',
	'items': [{
			'@id': '/api/v4/audiences/e1fa7c93edda4541937899ad032b9051',
			'@type': 'Audience',
			'id': 'e1fa7c93edda4541937899ad032b9051',
			'created': '2021-06-30T17:57:51.765Z',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'match_type': 'ANY',
			'external_id': '',
			'country_codes': [],
			'dma_codes': [],
			'desc': 'Beverly Hills',
			'devices': [],
			'ip_networks': [],
			'zip_codes': ['90503'],
			'sub_audiences': [],
			'type': 'Single'
		}, {
			'@id': '/api/v4/audiences/abc11672b78c4d03bf4756ec3ea46a22',
			'@type': 'Audience',
			'created': '2021-06-30T22:32:09.362Z',
			'id': 'cc1c1672b78c4d03bf4756ec3ea46a45',
			'owner': 'abc123def456ghi789jkl012mno345pq',
			'match_type': 'ANY',
			'external_id': 'NorthAmerica',
			'country_codes': ['CA', 'MX', 'US'],
			'dma_codes': [],
			'desc': 'My New audience',
			'devices': [],
			'ip_networks': [],
			'zip_codes': [],
			'sub_audiences': [],
			'type': 'Single'
		}
	],
	'total_items': 2
}