Segment Reach API
If you are a DMP client, you can implement the segment reach (SegmentInventory) web
service to get the estimated number of unique users for the individual categories and segments in your audience and for the audience itself. The reach is based on the number of users seen in the category, segment, or audience based on the current audience configuration. Audience reach shows whether the audience is big enough to generate your desired number of impressions before delivering it to a media execution platform.
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.
For help with this API, contact My Oracle Support (MOS).
Service URI
The URI for the segment reach API is:
services.bluekai.com/Services/WS/SegmentInventory
Related API calls
Here are the API calls you will typically make before and after you use the segment reach API:
| Related API | Use case |
|---|---|
| Audiences API | Create the audience once you have verified its reach. You can call the segment reach API before and after the audience API. You can call the segment reach API first to get the reach of an audience to verify that it meets your desired scale before you create it, or you can call the audience API first to create an audience and then verify its reach with the segment reach API. |
| Campaigns API | Create instructions for delivering your target audience to DMP partners. |
| Categories API | View the first- and third-party categories that you can use to create your audience before you use the segment reach API. |
Audience creation reference
In the Oracle Data Cloud APIs, an audience is represented by a series of segments that are combined with AND logic
{"AND":[{"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 (category ID = 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 a segment reach API POST request that includes a single segment with one category:
{"AND":[{"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 (category ID = 7628) and In-Market > Retail > Video Games > Systems > Microsoft > XBOX (category ID = 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 segment reach API POST request that includes multiple categories in a single segment:
{"AND":[{"AND":[{"OR":[{"cat":7624},{"cat":7628}]}]}]}
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 (category ID = 139) to one segment and In-Market > Travel > Cruises (category ID = 6089) to another segment, the user needs to have been tagged with both categories to be included.
The following code snippet demonstrates a JSON-body for a segment reach API POST request that includes multiple segments:
{"AND":[{"AND":[{"OR":[{"cat":139}]},{"OR":[{"cat":6089}]}]}]}
Including multiple segments with multiple categories
If your target audience includes multiple segments, you can include multiple categories in one or more of the segments.
For example, you can include multiple car model categories in one segment, and geographic and demographic categories in another segment.
The following code snippet demonstrates a JSON-body for a segment reach API POST request that includes multiple segments with multiple categories in each segment:
{"AND":[{"AND":[{"OR":[{"cat":2150},{"cat":355}]},{"OR":[{"cat":2095},{"cat":2098}]}]}]}
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 In-Market > Travel > Cruises (categoryID = 6089) but exclude users in 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 a segment reach API POST request that includes and excludes different segments:
{"AND":[{"AND":[{"OR":[{"cat":18}]}]},{"NOT":{"AND":[{"OR":[{"cat":71},{"cat":5814}]}]}}]}
Setting the frequency
(Optional) You can specify the frequency in your segment reach API POST requests.
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":[{"AND":[{"OR":[{"cat":17,"freq":[10]}]}]}]}
To set a range of frequencies (for example 10 to 20), use the following syntax:
{"AND":[{"AND":[{"OR":[{"cat":17,"freq":[10,20]}]}]}]}
Setting the country
Countries: To get the reach of your audience for one or more countries, include the countries parameter in the query string for each country. For example, to get the reach of your audience in United States and the United Kingdom, include the two-letter ISO 3166-1 alpha-2 country code for each country using the following syntax:
countries=US,UK
Important: By default, the segment reach returns data as if you were searching for US-only data. If you want to include all countries, you need to specify countries=ALL.
Setting the ID source
To specify the ID source, use the device_type parameter with one of the following codes:
1: Oracle Data Cloud 3rd Party Desktop Cookie ID3: Oracle Data Cloud Mobile Cookie ID6: Google Advertising ID (AdID)9: Apple IDFA
The default is all ID sources supported by the audience.
To include the inventory figures in the response according to ID source, set the doPerIdTypeReach parameter to true. The default value is false.
Specifying a partner ID
If your user account is associated with multiple seats, you can include a partner IDs in the query string to determine which seat to target. (Your partner ID is listed in the upper right-hand corner of the platform UI.) To specify the partner ID, you use the pid parameter .For example:
services.bluekai.com/Services/WS/SegmentInventory?pid=999999
Setting the device (Deprecated)
You can get the reach of your audience based for a specific device type (desktop or mobile) by including the deviceTypeID parameter in the query string. For example to get the reach of your audience on mobile devices only, you would use the following syntax:
services.bluekai.com/Services/WS/SegmentInventory?deviceTypeID=2
The default device type is all (desktop and mobile). The Oracle Data Cloud APIs support the following device type codes:
0: All (desktop and mobile)1: Desktop2: Mobile
Warning: The deviceTypeID parameter is deprecated. Use device_typeinstead.
Segment reach POST response summary
The segment reach API POST request returns the reach for the specified audience, segments, and categories.
The following audience properties can be returned:
| Property | Description |
|---|---|
_cpuTime
|
(Oracle internal use only) The POST response time (in milliseconds) |
multiplier
|
Oracle internal use only |
namespaces
|
Oracle internal use only |
nvars
|
Oracle internal use only |
priceFloor
|
Oracle internal use only |
reach
|
The total number of unique users seen in the category, segment, or audience based on its current configuration |
status
|
This value will be QUERY_SUCCESS for successful calls to the segment reach API. |
The following segment properties can be returned:
| Property | Description |
|---|---|
nvars
|
Oracle internal use only |
priceFloor
|
Oracle internal use only |
reach
|
The total number of unique users seen in the category, segment, or audience based on its current configuration |
The following category properties can be returned:
| Property | Description |
|---|---|
cat
|
The unique ID assigned to the category |
freq
|
The frequency used in the query for the category (if specified). The frequency represents the minimum number of times users must have qualified for a category since they were initially tagged with it to be included in the query. |
nvars
|
Oracle internal use only |
reach
|
The total number of unique users seen in the category, segment, or audience based on its current configuration |