Audiences API
If you are a DMP client, you can implement the audience web service to create and manage audiences. An audience contains the users you want deliver to Oracle Data Cloud partners for targeting, modeling, or optimization. You can also analyze an audience to expand it, identify trends, and analyze the performance of its categories.
For example, you can use the audiences API to create a simple audience that includes one segment (such as users interested in purchasing a smart phone) or you can create a complex audience that includes multiple segments (such as user interested in purchasing smart phones and users interested in purchasing laptops), while excluding other segments (such as, users with a specific range of ages and household incomes). For details about creating audiences, see the audience creation reference.
Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.
In this topic
Explore the API
The embedded I/O doc below enables you to explore the API. The I/O doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.
Open the link below in a new tab to see the I/O doc in a three-pane format.
https://audiences2.docs.apiary.io
For help with this API, contact My Oracle Support (MOS).
Service URI
The URI for the audiences API is:
services.bluekai.com/Services/WS/audiences
Audiences API use cases
What kind of Audiences can I get from the audiences API?
- Created audiences: Audiences you have created using the audience builder in the Oracle Data Cloud platform or the audiences API.
- Received audiences: Audiences that a DMP client has shared with you. You can create a campaign using the received audience or analyze it.
Audience sharing is typically used by DMP clients to send their audiences to an agency who will then run the campaign for them.
Audiences can be shared using the audience grant API or the audience management tool in the Oracle Data Cloud platform.
When do I use the audiences API?
- Audience creation and inventory retrieval
- Audiences with first-party categories: If you are a DMP client or an audience recipient, you can use the audiences API to create new audiences or get existing audiences. You can then use the segment reach API to get the number of unique users in the audiences.
- Audiences with third-party categories: If you are a data buyer, you can use the audiences API to create new audiences and get existing audiences that include third-party categories. You can then use the segment reach API to get the number of unique users in the audience.
- Audience discovery: If you are a DMP client or data buyer that has created audiences, you can use the audiences API to get the composition and configuration of an audience. This helps you create new audiences with similar categories and settings.
- Audience analytics: If you are a data app partner who is programmatically running audience analytics, you can call the GET method and use the categories in the returned audience as the input for creating audience discovery reports.
- Data delivery configuration: You can use the audiences API to create a grouping of categories to be delivered to a partner. If you want to deliver an existing audience, use the audiences API’s GET function to get the audience you want to send.
- Data mapping: Data mapping takes place at the campaign level. This is because the
campaignID
parameter is included with user data delivered via server data transfer, which is the preferred data delivery method.
Related API calls
API calls you will typically make before and after you use the audiences API:
Related API calls | Use case |
---|---|
Audience grant API | Share your audience with other DMP partners. |
Campaigns API | Create instructions for delivering your target audience to DMP partners. |
Pixel URL API | Associate a destination with your campaign. |
Segment reach API | Get the estimated number of unique user in an audience before creating and delivering it. |
Categories API | View the first- and third-party categories that you can use to create your target audience. |
User data API | Programmatically deliver the campaigns and categories for which users have qualified. |
GET response summary
The audiences API GET request returns an audience or a list of audiences.
Property | Type | Description |
---|---|---|
archived
|
boolean | Indicates whether an audience has been archived. Data is not delivered for archived audiences. |
audienceGrants
|
object |
An object containing properties related to audiences you have received from another DMP partner. For each audience shared with you, the following properties are included:
|
audienceID
|
integer | The unique identifier assigned to the audience |
campaigns
|
object |
An object including a list of the campaigns to which the audience has been added. For each campaign, the following properties are included:
|
createDate
|
date | The date when the audience was created (in YYYY-MM-DD format). |
countryCodes
|
integer |
The two-letter ISO 3166-1 alpha-2 country codes of the countries the audience is targeting. |
deviceTypeId
|
integer |
Indicates on which devices your audience is targeting users. This may be one of the following values:
|
name
|
string | The user-specified name of the audience. |
partnerID
|
integer | The unique identifier assigned to your Oracle Data Cloud platform seat. |
prospecting
|
boolean | A legacy field. |
recency
|
integer | The maximum number of days users must have been tagged with a category attribute to be included in your audience. The default recency is 0, which means 90 days. |
retargeting
|
boolean | A legacy field. |
segment
|
object |
An object representing an audience with the following structure:
This object is populated only in GET (read) responses. It is empty for GET (list) responses. |
status
|
string |
Indicates whether the audience is being shared. This property may be one of the following values:
|
totalCount
|
integer | The total number of audiences returned by the GET (list) request |
Audience creation reference (for POST and PUT requests)
In Oracle Data Cloud APIs, an audience is represented by a series of segments that are combined with AND logic
{ "AND": [<Segment1>, <Segment2>, ...] }
where each segment has one or more categories that are combined using OR logic:
{"OR": [{"cat1", <categoryID>}, {"cat2", <categoryID>), ...] }
If your audience includes multiple segments, the user must meet the criteria in all of the segments to be included in your target audience (an AND condition).
If a segment includes multiple categories, a user only needs to have been tagged with one of the categories to be included in the segment (an OR condition).
Adding a category to a single segment
You can create a simple audience that includes a single segment with one category.
For example, if you add In-Market > Autos (categoryID = 17) to a segment, the user needs to have been tagged with that category to be included in your audience.
The following code snippet demonstrates a JSON-body for an audiences API POST request that includes a single segment with one category:
"segment": {"and": [{"or": [{"cat": 17}]}]}
Adding multiple categories to a segment
You can add multiple categories to a segment, which creates an OR condition. This means that a user only needs to have been tagged with one of the categories in the segment to be included in your target audience.
For example, if you add In-Market > Retail > Video Games > Systems > Sony > Playstation (categoryID = 7628) and In-Market > Retail > Video Games > Systems > Microsoft > XBOX (categoryID = 7624) to a segment, the user only needs to have been tagged with one of the video game systems to be included.
The following code snippet demonstrates a JSON-body for a audiences API POST request that includes multiple categories in a single segment:
segment": {"AND": [{"OR": [{"cat": 7624},{"cat": 7628,"freq": [1, null]}]}]}
Including multiple segments in an audience
Your target audience may also include multiple segments, which creates an AND condition. This means that a user must meet the criteria in all of the segments to be included in your target audience.
For example, if you add In-Market > Travel > Air Travel (categoryID = 139) to one segment and In-Market > Travel > Cruises (categoryID = 6089) to another segment, the user needs to have been tagged with both categories to be included.
The following code snippet a JSON-body for a audiences API POST request that includes multiple segments:
"segment": {"AND": [{"OR": [{"cat": 139}]},{"OR": [{"cat": 6089}]}]}
Excluding segments
Your target audience may exclude one or more categories in a segment, which creates a NOT condition. This means that users in the excluded segment will not be included in your target audience.
For example, if you include users in the In-Market > Travel > Cruises category (categoryID = 6089) but exclude users in the Demographic > Premium Demographic > Income > $0-$14,999 (categoryID = 5814) and Demographic > Premium Demographic > Income > $15,000-$19,999 (categoryID = 71) categories, those users who are in-market for a cruise but are in the specified lower incomes will not be included from your target audience.
The following code demonstrates a JSON-body for an audiences API POST request that includes and excludes different segments:
"segment": {"AND": [{"OR": [{"cat": 18}]},{"NOT": {"OR": [{"cat": 71},{"cat": 5814}]}}]}
Setting the frequency and target device
(Optional) You can specify the frequency and target device in your audiences API POST and PUT requests.
-
Frequency
: Frequency represents the number of times users must have qualified for a category since they were initially tagged with it to be included in the query.For example, to set the minimum frequency to 10 using the previous example, you would include the
freq
parameter in the JSON body using the following syntax:{"AND": [{"OR": [{"cat": 17,"freq":[10]}]}]}
To set a range of frequencies (for example 10 to 20), use the following syntax:
{"AND": [{"OR": [{"cat": 17,"freq":[10,20]}]}]}
-
Device
: You can get the reach of your audience based for a specific device type (desktop or mobile) using thedevice_type
parameter. For example to get the reach of your audience on mobile devices only, you would use the following syntax:{"AND": [{"OR": [{"cat": 17}]}],"device_type": "mobile"}
The default device type is All (desktop and mobile). The APIs support the following device types: all (desktop and mobile), desktop, or mobile.