The endpoints for the Audience Management API V1 facilitate:
- The General Audience Management Workflow
- Working with Audience Definitions
For details on API authentication, see Authentication for FreeWheel Demand APIs.
General Audience Management Workflow
Audience Management API V1 allows you to search, filter, and obtain descriptive metadata on segments available in Data Suite. You can also retrieve sizing estimates for segments and boolean combinations of segments, in the context of household reach and ID type across configurable geographic areas.
Using the Audience Management API V1 workflow, you can:
Retrieve lists of advertiser Industry categories
Retrieve lists of available Data Providers per relevant Industry category
Retrieve lists of Segments available from those Data Providers
Construct Audience Definitions using Segments
You may wish to cache responses describing industry categories and available data providers rather than repeating them for every incremental workflow step.
Working with Audience Definitions
Once you have determined a satisfactory combination of segments, you can save the combination as an Audience Definition and export it to FreeWheel's core ad server. The Audience Definition can then be used for forecasting, ad selection, and reporting in MRM.
To work with an audience definition you need to:
|Create a temporary audience definition||This lets you see audience size estimates, but won't create a permanent resource in Data Suite.|
|Modify the temporary audience definition||Add and remove segments to change the size and composition of the audience definition until the desired state is met.|
|Create a permanent audience definition||In order to view sizing information and save a segment as part of an Audience Definition, the segment and its associated taxonomy metadata must have been previously ingested into Data Suite.|
|Retrieve an audience definition||You can paginate and filter your results.|
Audience Management API V1 Glossary
|Segment||The most granular level of behavioral / demographic user grouping, as received by Data Suite from a data provider|
|Audience Definition||A boolean combination of one or more segments. A segment or segments must be saved under the heading of a parent Audience Definition in order to be exported to MRM for execution purposes.|
When creating boolean segment combinations within Audience Definitions:
|Industry||A business category descriptor associated with a given advertiser. Data usage restrictions are configurable against the Industry dimension. A truthful advertiser Industry must be declared for all Audience Definitions.|
|Audience Partner||The immediate upstream entity delivering a given segment to FreeWheel.|
For example, data vendor A is a reseller for segments owned by data vendor B. Data vendor A sends a segment owned by data vendor B to Data Suite. Data vendor A is the audience partner for that segment.
|Data Provider||The root owner of a given segment.|
For example, data vendor A is a reseller for segments owned by data vendor B. Data vendor A sends a segment owned by data vendor B to Data Suite. Data vendor B is the data provider for that segment.
|id||String||FreeWheel-generated segment ID|
|name||String||FreeWheel-provided friendly name for the segment|
|audience_partner||String||FreeWheel-provided ID representing source of immediate upstream data export to FreeWheel|
|data_provider_id||String||FreeWheel-provided ID representing data owner upstream of audience_partner (if applicable.) This field is intended to accommodate data reseller arrangements.|
|data_source_id||String||FreeWheel-provided ID representing initial origin of the segment data. It is frequently the same value as data_provider_id, unless a segment was initially seeded by first-party data.|
|client_id||String||Numeric FreeWheel network ID of network(s) that have segment access. A value of -1 indicates the segment is available for use by any network.|
|level||Integer||Deprecated field, formerly used to indicate segment hierarchy where applicable. Expect value of 0.|
|parent_id||Integer||Deprecated field, formerly used to indicate segment hierarchy where applicable. Expect value of 0.|
|cpm||Integer||Cost per thousand|
|count||Integral||Segment membership size based on an estimate rather than the actual population. It is generated through the sketch function.|
|provider_segment_id||String||Segment ID provided by the audience partner|
Audience Definition Object
|id||string||FreeWheel-generated audience ID|
|name||string||FreeWheel-provided friendly name for the audience|
|metadata||array||Embeds the segment and target objects.|
|segments||array||A subfield of metadata providing the segment metadata for all targets in the audience so that these properties can be added to your user interface (e.g. listing targets as names)|
|restrictions||integer(s)||Numeric FreeWheel industry IDs of industries not permitted to use a given segment|
|targets||array||The sub-fields within this array describe boolean relationships between segments in the Audience Definition. Target is synonymous with segment in this case.|
|kind||enum||include or exclude|
|type||string||The type of target: segment or geo|
|target_ids||string||Synonymous with FreeWheel segment ID(s)|
|std_dev||type||Absolute value of one standard deviation from the size estimate|
The audience identifier type the estimate is for:
|lower_bound||integer||The lowest limit for your estimate|
|upper_bound||integer||The highest limit for your estimate|
|created_at||Timestamp, e.g., "2021-10-26T18:55:34.206244722Z"||The date and time at which your audience was created|
|updated_at||Timestamp, e.g., "2021-10-26T18:55:34.206244722Z"||The date and time at which your audience was updated|
Data Provider Object
|id||string||FreeWheel-provided identifier for the data provider|
|label||string||FreeWheel-provided friendly name for the data provider. It generally has the same value as id (above).|
|restrictions||Integer||Indicates an Industry category ID that the data provider may have restricted from using its data.|
See Visibility and Restrictions in the Data Provider Object below.
Segments from data provider X carrying hypothetical restriction 3, should only be made UI visible in the user interface to API users who have passed the industry ID associated with restriction 3.
|Visibility IDs are numeric restriction IDs from the Segment Permissions API, which ensure that you see the best version of the data that you have permission to view.|
This field only exists to pass flags indicating restriction relationships. You can choose whether or not your user interface reflects the restrictions.
See Visibility and Restrictions in the Data Provider Object below.
Visibility and Restrictions in the Data Provider Object
When you have rights to two sets of data for your application, one favored and one disfavored, the visibility ID acts as a complement to your restrictions; that is, if one data provider is restricted, then the other is visible and can be presented in your app.
The visibility ID indicates that, while the permission to use a disfavored data set exists, that data set should only be shown when the restriction to the favored data set is applied.
If you are restricted from seeing a particular data set, then that data is hidden and you can view the data from the provider from which you are not restricted.
If you are not restricted from seeing a particular data set, the visibility flag filters out the disfavored data set to which you have access and enables you to view the superior data sets. It is recommended that you use the favored data set.
Sample Business Use Case
Segment A and segment B have similar business purposes/definitions, but different underlying data sources. The data provider prefers to sell access to segment A over segment B, but for business reasons some clients may not be allowed to use segment A.
If an API user passes an industry ID that is restricted from using segment A, the desired user interface experience is to show segment B in its place.
If an API user passes an industry ID that is allowed to use segment A, then the desired user interface experience is to show only segment A, even though that user's industry ID is not restricted from using segment B.
|page||integer||The number of pages for your list|
|per_page||integer||The number of results per page for your list|
|total_page||integer||The total number of pages in your returned list|
|total_count||integer||The total number of results returned in your list|