Categories API
You can use the categories API to retrieve, create, update, and filter category data in your Oracle Data Cloud taxonomy, which is a hierarchical tree structure that includes all your available categories. You can select categories from the taxonomy to build target audiences by grouping the categories into segments using OR logic and then include and exclude individual segments using AND or NAND logic.
Important: The Categories API deprecates the self-classification category and taxonomy APIs. If you are using these old APIs, you should migrate to this one to benefit from its additional parameters and features. These new features include the ability to create categories anywhere in your taxonomy, edit categories created by the Oracle Data Cloud Services Team, use new owner and public views to retrieve 1st and/or 3rd-party categories, and view the reach of your categories (by country and ID source).
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 categories API is:
taxonomy.bluekai.com/taxonomy/categories
Schema
The URI for the categories API schema is:
taxonomy.bluekai.com/taxonomy/categories/category.schema
{
"$schema" : "https://json-schema.org/draft-04/schema#",
"id" : "#category",
"type" : "object",
"title" : "Category Schema",
"description" : "The details of a particular Category",
"additionalProperties" : false,
"properties" : {
"id" : {
"type" : "integer",
"description" : "ID of a category",
"minimum" : 1,
"o:queryable" : "true"
},
"name" : {
"type" : "string",
"description" : "Name of a category",
"minLength" : 1,
"maxLength" : 255,
"o:queryable" : "true"
},
"parentCategory" : {
"type" : "object",
"description" : "Parent of a category",
"properties" : {
"id" : {
"type" : "integer",
"description" : "ID of a category",
"minimum" : 1
},
"name" : {
"type" : "string",
"description" : "Name of a category",
"minLength" : 1,
"maxLength" : 255
}
},
"required" : [ "id" ]
},
"description" : {
"type" : "string",
"description" : "Generic Description of a category"
},
"notes" : {
"type" : "string",
"description" : "Notes for a category"
},
"partner" : {
"type" : "object",
"description" : "Owner partner of a category",
"properties" : {
"id" : {
"type" : "integer",
"description" : "ID of a partner"
},
"name" : {
"type" : "string",
"description" : "Name of a partner",
"minLength" : 1,
"maxLength" : 255
}
}
},
"vertical" : {
"type" : "object",
"description" : "Vertical of a category",
"properties" : {
"id" : {
"type" : "integer",
"description" : "ID of a Vertical",
"minimum" : 1
},
"name" : {
"type" : "string",
"description" : "Name of a Vertical",
"minLength" : 1,
"maxLength" : 255
}
}
},
"isForNavigationOnlyFlag" : {
"type" : "boolean",
"description" : "If true, this category will be a parent node used for navigation and cannot be added to an audience"
},
"ownershipType" : {
"enum" : [ "firstParty", "secondParty", "thirdParty" ],
"description" : "Describes ownership type of this category (read-only field)"
},
"isLeafFlag" : {
"type" : "boolean",
"description" : "flag to indicate if this category is a leaf node in the current view (read-only field)"
},
"categoryPrice" : {
"type" : "number",
"description" : "the price of a category"
},
"universalPrice" : {
"type" : "number",
"description" : "the universal price of a category"
},
"buyerPrice" : {
"type" : "number",
"description" : "the buyer price of a category"
},
"stats" : {
"type" : "object",
"description" : "various statistics for this category",
"properties" : {
"reach" : {
"javaType" : "java.lang.Long",
"description" : "reach for this category (read-only field)"
},
"audienceCount" : {
"type" : "integer",
"description" : "number of audiences using this category (read-only field)"
},
"campaignCount" : {
"type" : "integer",
"description" : "number of campaigns using this category (read-only field)"
}
}
},
"pathFromRoot" : {
"type" : "object",
"description" : "Path from root to a particular category",
"properties" : {
"ids" : {
"type" : "array",
"items" : {
"type" : "integer"
},
"description" : "List of category ids that form a path from the root",
"minItems" : 1
},
"names" : {
"type" : "array",
"items" : {
"type" : "string"
},
"description" : "List of category names that form a path from the root",
"minItems" : 1
}
}
},
"status" : {
"enum" : [ "active", "deleted", "draft" ],
"description" : "Describes status of current resource",
"default" : "active"
},
"links" : {
"type" : "array",
"description" : "Link objects mandated by Oracle Rest standards",
"items" : {
"$ref" : "orarestschemas.json#definitions/instanceLink"
}
}
},
"required" : [ "name", "parentCategory", "partner" ]
}
Read a category
To get information on a category, specify its ID as shown in the following GET call:
taxonomy.bluekai.com/taxonomy/categories/categoryID&bkuid=BKUID&bksig=BKSIG
For example, a GET call to /taxonomy/categories/288885
returns the following response:
{
"id" : 288885,
"name" : "Cat Owner",
"parentCategory" : {
"id" : 288884
},
"description" : "ACXM Interest, Pet Owner, Cat Owner",
"partner" : {
"id" : 303,
"name" : "Acxiom Corporation"
},
"vertical" : {
"id" : 23,
"name" : "Branded Data - Acxiom"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : true,
"pathFromRoot" : {
"ids" : [ 344, 24148, 150555, 319645, 288849, 288884, 288885 ],
"names" : [ "ROOT", "Branded Data", "Acxiom", "Basic Rate", "ACXM Interest", "Pet Owner", "Cat Owner" ]
},
"status" : "active",
"links" : [ ]
}
List categories
You can combine various query parameters to request a filtered set of categories.
List all the categories that you own
To view all the categories that you own, specify the required view
and partner.id
parameters as shown in the following GET call:
taxonomy.bluekai.com/taxonomy/categories?view=OWNER&partner.id=partnerID&bkuid=BKUID&bksig=BKSIG
Sample list response:
{
"items": [
{
"id": 322463,
"name": "Self-Classification",
"parentCategory": {
"id": 322462
},
"partner": {
"id": 2208
},
"verticalName": "Private DMP - Test Partner",
"isPublicFlag": false,
"isForNavigationOnlyFlag": true,
"ownershipType": "thirdParty",
"isLeafFlag": true,
"pathFromRoot": {
"ids": [
344,
322462,
322463
],
"names": [
"ROOT",
"Test Partner - Private",
"Self-Classification"
]
},
"status": "active",
"links": []
},
{
"id": 322462,
"name": "Test Partner - Private",
"parentCategory": {
"id": 344
},
"partner": {
"id": 2208
},
"verticalName": "Private DMP - Test Partner",
"isPublicFlag": false,
"isForNavigationOnlyFlag": true,
"ownershipType": "thirdParty",
"isLeafFlag": false,
"pathFromRoot": {
"ids": [
344,
322462
],
"names": [
"ROOT",
"Test Partner - Private"
]
},
"status": "active",
"links": []
}
],
"totalResults": 2,
"limit": 2,
"offset": 0,
"count": 2,
"hasMore": false
}
List the public categories
To view all the public (third-party) categories, specify view=PUBLIC
and your partner ID as shown in the following GET call:
taxonomy.bluekai.com/taxonomy/categories?view=PUBLIC&partner.id=partnerID&bkuid=BKUID&bksig=BKSIG
Note: It can take a while to get a response because this call includes so many categories.
Sample list response:
{
"items" : [ {
"id" : 1,
"name" : "Geographic",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people whose geographic location was either self-declared or determined from their IP address. Locations in the United States are organized on the basis of U.S. Census Bureau Core Based Statistical Areas.",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Geographic"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 1 ],
"names" : [ "ROOT", "Geographic" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 8,
"name" : "Self-Declared",
"parentCategory" : {
"id" : 1
},
"description" : "This category contains people who submitted information about their geographic location.",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Geographic"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : true,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 1, 8 ],
"names" : [ "ROOT", "Geographic", "Self-Declared" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 65,
"name" : "United States",
"parentCategory" : {
"id" : 8
},
"description" : "This category contains people who submitted information about their geographic location, arranged by U.S. state.",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Geographic"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 1, 8, 65 ],
"names" : [ "ROOT", "Geographic", "Self-Declared", "United States" ]
},
"status" : "active",
"links" : [ ]
},
...
{
"id" : 542544,
"name" : "76 & Older",
"parentCategory" : {
"id" : 542532
},
"description" : "This audience contains people who have been validated as 76 and older.",
"notes" : "",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Oracle - Demographic"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false, "ownershipType" : "thirdParty",
"isLeafFlag" : true,
"pathFromRoot" : {
"ids" : [ 344, 671901, 697212, 215759, 542532, 542544 ],
"names" : [ "ROOT", "Oracle", "Demographic", "Validated Demographic", "Age Narrow", "76 & Older" ]
},
"status" : "active",
"links" : [ ]
} ],
"count" : 63178
}
List the buyer view of categories
To view all the public (third-party) categories plus the first- and second-party categories in your private (managed) and self-classification trees, specify view=BUYER
and your partner ID as shown in the following GET call:
taxonomy.bluekai.com/taxonomy/categories?view=BUYER&partner.id=partnerID&bkuid=BKUID&bksig=BKSIG
Note: It can take a while to get a response because this call includes so many categories.
Sample list response:
{
"items" : [ {
"id" : 369765,
"name" : "Television",
"parentCategory" : {
"id" : 344
},
"description" : "This vertical contains viewership data aggregated at the household level across TV show, viewing frequency, daypart, and genre.",
"notes" : "",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Television"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 369765 ],
"names" : [ "ROOT", "Television" ]
},
"status" : "active",
"links" : [ ]
},
...
{
"id" : 823501,
"name" : "3+",
"parentCategory" : {
"id" : 458880
},
"description" : "This audience is comprised of individuals who have more than three children in their household.",
"notes" : "",
"partner" : {
"id" : 2992
},
"vertical" : {
"name" : "Branded Data - Infogroup"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : true,
"pathFromRoot" : {
"ids" : [ 344, 24148, 458841, 557017, 458842, 458843, 458866, 458878, 458879, 458880, 823501 ],
"names" : [ "ROOT", "Branded Data", "Infogroup, Inc", "Infogroup Corporate", "Consumer", "Demographics", "Family", "Children", "Yes", "Number of Children", "3+" ]
},
"status" : "active",
"links" : [ ]
} ],
"count" : 63239
}
List example for categories without reach
The following list call requests all categories to a depth of four levels (numOfLevels=4
) from the root category (parentCategory.id=344
). By default, the response does not include reach statistics for each category.
https://taxonomy.bluekai.com/taxonomy/categories?parentCategory.id=344&numOfLevels=4&partner.id=partnerID&view=BUYER&bkuid=BKUID&bksig=BKSIG
Sample list response without reach statistics:
{
"items" : [ {
"id" : 369765,
"name" : "Television",
"parentCategory" : {
"id" : 344
},
"description" : "This vertical contains viewership data aggregated at the household level across TV show, viewing frequency, daypart, and genre.",
"notes" : "",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Television"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 369765 ],
"names" : [ "ROOT", "Television" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 1,
"name" : "Geographic",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people whose geographic location was either self-declared or determined from their IP address. Locations in the United States are organized on the basis of U.S. Census Bureau Core Based Statistical Areas.",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Geographic"
},
"isPublicFlag": true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 1 ],
"names" : [ "ROOT", "Geographic" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 3,
"name" : "In-Market",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people who have demonstrated intent to make purchases in several key verticals. Intent is demonstrated by activities like searching for particular products, reading product specifications, adding items to a shopping cart, placing bids in online auctions, and requesting quotes for goods and services.",
"notes" : "DO NOT EDIT THIS CATEGORY UNTIL QUALIFIED IN-MARKET IS PUBLIC",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Private - Default"
},
"isPublicFlag": true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 3 ],
"names" : [ "ROOT", "In-Market" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 43876,
"name" : "Past Purchases",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people who are likely to have made various purchases.",
"notes" : "",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Past Purchases"
},
"isPublicFlag": true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 43876 ],
"names" : [ "ROOT", "Past Purchases" ]
},
"status" : "active",
"links" : [ ]
},
...
{
"id" : 802803,
"name" : "West Midlands",
"parentCategory" : {
"id" : 802654
},
"description" : "Targetable profiles > CACI Limited > UK Towns > West Midlands",
"partner" : {
"id" : 4521
},
"vertical" : {
"name" : "Branded Data - CACI Limited"
},
"isPublicFlag": true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"pathFromRoot" : {
"ids" : [ 344, 24148, 801846, 802654, 802803 ],
"names" : [ "ROOT", "Branded Data", "CACI Limited", "UK Towns", "West Midlands" ]
},
"status" : "active",
"links" : [ ]
} ],
"count" : 12518
}
List example for categories with reach
The following list call requests all categories to a depth of four levels and it includes reach statistics for each category because it specifies showReach=true
.
https://taxonomy.bluekai.com/taxonomy/categories?parentCategory.id=344&numOfLevels=4&partner.id=partnerID&showReach=true&view=BUYER&bkuid=BKUID&bksig=BKSIG
The response includes a stats
object for each category that specifies "reach" : integer
.
Important: If you set showReach
to true
, the response time may increase significantly depending on the number of categories being returned and the specified options.
Sample list response with reach statistics:
{
"items" : [ {
"id" : 369765,
"name" : "Television",
"parentCategory" : {
"id" : 344
},
"description" : "This vertical contains viewership data aggregated at the household level across TV show, viewing frequency, daypart, and genre.",
"notes" : "",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Television"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"stats" : {
"reach" : 792431680
},
"pathFromRoot" : {
"ids" : [ 344, 369765 ],
"names" : [ "ROOT", "Television" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 1,
"name" : "Geographic",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people whose geographic location was either self-declared or determined from their IP address. Locations in the United States are organized on the basis of U.S. Census Bureau Core Based Statistical Areas.",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Geographic"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"stats" : {
"reach" : 8012719040
},
"pathFromRoot" : {
"ids" : [ 344, 1 ],
"names" : [ "ROOT", "Geographic" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 3,
"name" : "In-Market",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people who have demonstrated intent to make purchases in several key verticals. Intent is demonstrated by activities like searching for particular products, reading product specifications, adding items to a shopping cart, placing bids in online auctions, and requesting quotes for goods and services.",
"notes" : "DO NOT EDIT THIS CATEGORY",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Private - Default"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"stats" : {
"reach" : 983929920
},
"pathFromRoot" : {
"ids" : [ 344, 3 ],
"names" : [ "ROOT", "In-Market" ]
},
"status" : "active",
"links" : [ ]
}, {
"id" : 43876,
"name" : "Past Purchases",
"parentCategory" : {
"id" : 344
},
"description" : "This category contains people who are likely to have made various purchases.",
"notes" : "",
"partner" : {
"id" : 0
},
"vertical" : {
"name" : "Past Purchases"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"stats" : {
"reach" : 1206922560
},
"pathFromRoot" : {
"ids" : [ 344, 43876 ],
"names" : [ "ROOT", "Past Purchases" ]
},
"status" : "active",
"links" : [ ]
},
...
{
"id" : 802803,
"name" : "West Midlands",
"parentCategory" : {
"id" : 802654
},
"description" : "Targetable profiles > CACI Limited > UK Towns > West Midlands",
"partner" : {
"id" : 4521
},
"vertical" : {
"name" : "Branded Data - CACI Limited"
},
"isPublicFlag" : true,
"isForNavigationOnlyFlag" : false,
"ownershipType" : "thirdParty",
"isLeafFlag" : false,
"stats" : {
"reach" : 12856320
},
"pathFromRoot" : {
"ids" : [ 344, 24148, 801846, 802654, 802803 ],
"names" : [ "ROOT", "Branded Data", "CACI Limited", "UK Towns", "West Midlands" ]
},
"status" : "active",
"links" : [ ]
} ],
"count" : 12518
}
Export categories
To export categories, filter your GET request with the desired query parameters as shown in the following example:
/taxonomy/categories/export?view=BUYER&partner.id=2208&showReach=true&parentCategory.id=17&parentCategory.id=3&numOfLevels=1
Sample response:
17 Autos ROOT>In-Market>Autos 3 252351600
3 In-Market ROOT>In-Market 344 1016820000
Note: Export does not support the addStats
parameter.
Create a category
To create a category, include your partner ID and a request body in the following POST call:
/taxonomy/categories?partner.id={yourPartnerId}
Sample request body specifying required fields:
{
"name": "Test node",
"parentCategory": {
"id": 410579
},
"partner": {
"id": 2362
}
}
If not specified, the values for type
and verticalName
are inherited from the parent category. Default values are used for other optional fields if not specified in the POST request.
Response:
{
"id": 420063,
"name": "Test node",
"parentCategory": {
"id": 410579,
"name": "Child2"
},
"links": {
"self": "https://taxonomy.bluekai.com/taxonomy/categories/420063",
"parent": "https://taxonomy.bluekai.com/taxonomy/categories/410579"
}
}
Bulk create
To create multiple categories, include your partner ID and a request body in the following POST call:
/taxonomy/categories?partner.id={yourPartnerId}
Sample request body specifying multiple categories:
[
{
"name": "Test node1",
"parentCategory": {
"id": 322463
},
"partner": {
"id": 2208
}
},
{
"name": "Test node2",
"parentCategory": {
"id": 322463
},
"partner": {
"id": 2208
}
}
]
If not specified, the values for type
and verticalName
are inherited from the parent categories. Default values are used for other optional fields if not specified in the POST request.
Response:
{
"items": [
{
"httpStatusCode": 200,
"item": {
"id": 3,
"name": "In-Market",
"parentCategory": {
"id": 344,
"name": "ROOT"
},
"links": {
"self": "https://taxonomy.bluekai.com/taxonomy/categories/3",
"parent": "https://taxonomy.bluekai.com/taxonomy/categories/344"
}
}
},
{
"httpStatusCode": 200,
"item": {
"id": 17,
"name": "Autos",
"parentCategory": {
"id": 3,
"name": "In-Market"
},
"links": {
"self": "https://taxonomy.bluekai.com/taxonomy/categories/17",
"parent": "https://taxonomy.bluekai.com/taxonomy/categories/3"
}
}
}
],
"size": 2
}
Bulk import (via file upload)
To create and edit multiple categories at the same time by uploading a TSV or TXT file:
- In the query string of your call to the Categories API,append
import
to the path.serviceUrl = 'https://taxonomy.bluekai.com/taxonomy/categories/import?partner.id={yourPartnerId}'
- In the
headers
field, set theContent-Type
tomultipart/form-data
.headers = {"Content-Type": "multipart/form-data; "Accept": "application/json","User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0"}
- Include a parameter that is set to the name of the .tsv or .txt file to be imported.
- Verify that the import file has the following columns:
Field Data type Required? Description Id
string required (for editing catgories) The unique ID assigned to the category. This column is required for editing categories via bulk import because bulk import identifies categories based on the unique category IDs.. Name
string optional A unique, concise name for the category. The category will be listed by this name in your taxonomy. The name may be a maximum of 255 characters. You only need to provide a name if you arechanging the name of a category. Path
string required (for adding catgories) The full taxonomy path of the category. This column is required for adding categories via bulk importbecause it determines where they are added in your taxonomy. ParentCategory
int optional (required for moving categories) The unique ID assigned to the category directly above the selected category in your taxonomy. This column is required for moving categories via bulk import. Description
string optional A verbose summary of the type of users included in with this category. The description may be a maximum of 255 characters. Status
enum optional Select whether the category is to be placed in the Active or Draft state. The default value of this setting is based on the parent category. Changing the status of parent category also updates the status of all the child categories underneath it. If a parent node is in the Draft state, you cannot make any of its child nodes Active. - Active. The category is published to your taxonomy. This means that it is visible in the Audience Builder and Taxonomy Viewer, may be added to audiences, and may be shared with other clients.
- Draft. The category is only visible in the Taxonomy Manager. It cannot be used in the Audience Builder or Taxonomy Viewer, and it cannot be shared.
NavigationOnly
boolean optional Limits the functionality of this category to a parent node that cannot store user profile data, accumulate inventory, or be added to audiences. A navigation node essentially functions as a folder for one or more child categories.The default value is false. ExcludeFromAnalytics
boolean optional Excludes the category from audience analytics reports. The default value is false. MutuallyExclusiveChildren
boolean optional Makes the child categories under this category mutually exclusive (only the most recently tagged child category is in the user's profile). You may only create a flat list of mutually exclusive child categories. Mutually exclusive categories may not have any child categories below them---unless you mark the mutually exclusive categories as navigation-only nodes
Bulk import demo
The samplebulk_categories_import.py Python code demonstrates how to do a bulk category import using the Categories API. To run this script, you must have the following:
- Python 2.7+
- Requests library 1.2.3 (or later)
You can use PIP (a Python Package Installation tool) to help install the requests library. To download and install PIP, install the requests library, and then delete the PIP installation file, enter the following commands in your console:
curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
sudo python get-pip.py
sudo pip install requests
rm get-pip.py
To run this script, you need to create a TSV file named category_import.tsv (download template) that contains the categories you want to edit or create, and provide the following parameters:
url
: The URL of the Oracle Data Cloud platform's production environment (services.bluekai.com)verbosity
: Enter a series of four verbose options for printing information.partnerid
: The partner ID associated with the seat for which you are uploading categories.bkuid
: Your web service user keybksecretkey
: Your web service private key
The following example demonstrates the required syntax for calling this script:
bulk_categories_import.py --url https://services.bluekai.com -v -v -v -v --partnerid Partner ID--bkuid WebServiceUserKey --bksecretkey WebServicePrivateKey
#! /usr/bin/env python -B
# -*- coding: utf-8 -*-
import sys, requests, json, argparse, unittest, hmac, base64, urllib, urlparse, hashlib
def cli_options():
parser = argparse.ArgumentParser(description='Demo for Category REST API')
parser.add_argument('-u','--url', default='https://localhost:8080/', help='Web service base URL')
parser.add_argument('-p','--partnerid', help='Partner id to use with this request')
parser.add_argument('-i','--bkuid', default='', help='UID')
parser.add_argument('-k','--bksecretkey', default='', help='Secret key')
parser.add_argument('-v','--verbose', default=0, action='count', help='Prints additional information')
return parser.parse_args()
args = cli_options()
URL = args.url.strip()
PARTNERID = args.partnerid
BKUID = args.bkuid
BKSECRETKEY = args.bksecretkey
VERBOSITY = args.verbose
USER_AGENT = {'User-Agent':'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0'}
JSON_HEADERS = {'Content-Type': 'multipart/form-data', 'Accept':'application/json'}
COMMON_HEADERS = dict(USER_AGENT.items() + JSON_HEADERS.items())
class CategoryRest():
res = False
def info(self, message, verbosityLevel = 1):
if VERBOSITY >= verbosityLevel:
if not isinstance(message, basestring):
print json.dumps(message, indent=4)
else:
print message
def prepare_headers(self, headers = None):
if headers is None:
return COMMON_HEADERS.copy()
else:
return dict(COMMON_HEADERS.items() + headers.items())
def parse_query_params(self, query):
parameterList = query.split('&')
params = {}
if len(parameterList) > 0:
for entry in parameterList:
kvPair = entry.split('=')
params[kvPair[0]] = kvPair[1] if len(kvPair) > 1 else '';
return params
def prepare_request(self, endpoint, method = 'GET', params = None, data = None, headers = None, files = None, sign=True):
if files is not None:
headers.pop('Content-Type', None)
req = requests.Request(method, URL + endpoint, data = data, headers = headers, files = files)
prepared = req.prepare()
if sign:
if params is None:
params = {}
parsedUrl = urlparse.urlparse(URL)
parsedEndpoint = urlparse.urlparse(endpoint)
servletPath = "" if parsedEndpoint.path.strip().startswith("/") else "taxonomy/"
urlPath = parsedUrl.path.strip('/')
if urlPath:
urlPath = urlPath + '/'
fullPath = '/'+ urlPath + servletPath + parsedEndpoint.path.strip('/')
stringToSign = method + fullPath
params = dict(params.items() + self.parse_query_params(parsedUrl.query).items() + self.parse_query_params(parsedEndpoint.query).items())
queryParameterStr = '';
for key in params.keys():
if len(key) > 0:
if isinstance(params[key], list):
for listItem in params[key]:
value = urllib.quote(str(listItem))
stringToSign += value
queryParameterStr += urllib.quote(key) + '=' + value + '&'
else:
value = urllib.quote(str(params[key]))
stringToSign += value
queryParameterStr += urllib.quote(key) + '=' + value + '&'
if prepared.body is not None:
stringToSign += prepared.body
h = hmac.new(BKSECRETKEY, stringToSign.strip(), hashlib.sha256)
s = base64.standard_b64encode(h.digest())
signature = urllib.quote_plus(s)
finalURL = parsedUrl.scheme + '://' + parsedUrl.netloc + fullPath + '?' + queryParameterStr + 'bkuid=' + BKUID + '&bksig=' + signature
else:
finalURL = URL + endpoint
self.info('Sending %s request to: %s' %(method, finalURL))
prepared.url = finalURL
if VERBOSITY >=4:
print "Request object:"
for key, value in prepared.headers.iteritems():
print "%s: %s" % (key, value)
if prepared.body is not None and len(prepared.body)>0:
print ""
print prepared.body
return prepared
def post(self, endpoint, payload = None, params = None, headers = None, files = None):
if payload is not None:
data = payload if isinstance(payload, basestring) else json.dumps(payload)
else:
data = None
self.res = requests.Session().send(self.prepare_request(endpoint, method = 'POST', params = params, data = data, files = files, headers = self.prepare_headers(headers)), verify = False)
return self
def test_bulk_category_rest_create(self):
files = {'categoryFile': open('category_import.tsv', 'rb')}
created_categories = self.post('categories/import', files = files, params={'partner.id':PARTNERID}).res.json()
self.info(created_categories, 2)
instance=CategoryRest()
instance.test_bulk_category_rest_create()
Update a category
To update a category in your private taxonomy, include a request body with a PUT call that includes your partner ID and the category ID.
Sample PUT request:
/taxonomy/categories/{categoryId?partner.id={yourPartnerId}
Sample request body specifying category values:
{
"id": 322463,
"name": "Self-Classification - xyz",
"parentCategory": {
"id": 322462
},
"partner": {
"id": 2208,
"name": "Example Partner"
},
"vertical": {
"id": 336,
"name": "Private DMP - Example Vertical"
},
"isPublicFlag": false,
"isForNavigationOnlyFlag": true,
"ownershipType": "thirdParty",
"isLeafFlag": false,
"pathFromRoot": {
"ids": [
344,
322462,
322463
],
"names": [
"ROOT",
"Example Partner - Private",
"Self-Classification"
]
},
"status": "active",
"links": []
}
Response:
{
"id": 322463,
"name": "Self-Classification - xyz",
"parentCategory": {
"id": 322462,
"name": "Example Partner - Private"
},
"links": {
"self": "https://taxonomy.bluekai.com/taxonomy/categories/322463",
"parent": "https://taxonomy.bluekai.com/taxonomy/categories/322462"
}
}
Bulk update
To update multiple categories in your private taxonomy, specify them in the request body with your PUT call:
Sample bulk PUT request:
/taxonomy/categories?partner.id={yourPartnerId}
Sample request body specifying updates to multiple categories:
[
{
"id": 489266,
"name": "Test node1",
"parentCategory": {
"id": 322463
},
"description": "This is a sample category in our private taxonomy.",
"notes": "change 33",
"partner": {
"id": 2208,
"name": "Example Partner"
},
"vertical": {
"id": 336,
"name": "Private DMP - Example Vertical"
},
"isPublicFlag": true,
"isForNavigationOnlyFlag": false,
"ownershipType": "thirdParty",
"isLeafFlag": false,
"pathFromRoot": {
"ids": [
344,
322463,
489266
],
"names": [
"ROOT",
"Example Partner - Private",
"Self-Classification - xyz",
"Test node1"
]
},
"status": "active",
"links": []
},
{
"id": 489267,
"name": "Test node2",
"parentCategory": {
"id": 322463
},
"description": "This is a sample category in our private taxonomy.",
"notes": "change 33",
"partner": {
"id": 2208,
"name": "Example Partner"
},
"vertical": {
"id": 336,
"name": "Private DMP - Example Vertical"
},
"isPublicFlag": true,
"isForNavigationOnlyFlag": false,
"ownershipType": "thirdParty",
"isLeafFlag": false,
"pathFromRoot": {
"ids": [
344,
322463,
489267
],
"names": [
"ROOT",
"Example Partner - Private",
"Self-Classification - xyz",
"Test node2"
]
},
"status": "active",
"links": []
}
]
Response:
{
"items": [
{
"httpStatusCode": 201,
"item": {
"id": 489266,
"name": "Test node1",
"parentCategory": {
"id": 322463,
"name": "Self-Classification - xyz"
},
"links": {
"self": "https://taxonomy.bluekai.com/taxonomy/categories/489266",
"parent": "https://taxonomy.bluekai.com/taxonomy/categories/322463"
}
}
},
{
"httpStatusCode": 201,
"item": {
"id": 489267,
"name": "Test node2",
"parentCategory": {
"id": 322463,
"name": "Self-Classification - xyz"
},
"links": {
"self": "https://taxonomy.bluekai.com/taxonomy/categories/489267",
"parent": "https://taxonomy.bluekai.com/taxonomy/categories/322463"
}
}
}
],
"size": 2
}
Query parameters
The categories API supports following query parameters:
Parameter | Type | Description |
---|---|---|
addStats
|
boolean | If set to true , returns the stats object, which includes various statistics for the specified category, such as reach. The default value is false .Example: &addStats=true NoteExport does not support this parameter. |
countryCode
|
string | The two-letter code for the country by which to limit the statistics for the category. Defaults to US unless you specify other values.For more details, see countries API. Example: &showReach=true&countryCode=GB |
deviceType
|
string | (Deprecated) Specify either desktop or mobile to query statistics by device type.Example: &addStats=true&deviceType=mobile |
expand
|
boolean | If set to true , more details are returned. This parameter is only used for exporting a TSV file. The default value is false .Example: &expand=true |
idTypes
|
integer |
Filter by the ID source, which can be one of the following standard types:
&showReach=true&idTypes=9 |
numOfLevels
|
integer | Limit the category tree search by levels |
parentCategory.id
|
integer | Specify the ID of the parent category. The default value is 344 , which is the ROOT category.Example: &parentCategory.id=17 |
partner.id
|
integer | (Required) The unique ID of the partner This parameter can be used with other parameters, such as view .Example: &partner.id=1234 |
q
|
string |
Filter the returned categories according to their Example: |
recency
|
integer | Specify the maximum number of days since a user was last tagged with a category attribute for the category (the default is 90 days). This number is used to calculate reach. Example: addStats=true&recency=2 |
showPriceAt
|
date | A date in ISO 8601 date and time format (yyyy-MM-dd'T'HH:mm:ssZ) to determine what the price was on that date. For example: showPriceAt=2017-06-18T17:46:32-05:00 |
showReach
|
boolean | If set to true , include the inventory figures for the specified categories.If you set showReach to true , the response time may increase significantly depending on the number of categories being returned and the specified options. |
view
|
string | (Required) Filter's the response based on the following values:
partner.id with the view parameter. Example: |
FAQs
What type of data does the categories API provide?
The categories API can return all the information that you have access to about the following types of categories:
- First-party categories: Categories in your private first-party taxonomy. These categories are only available in your DMP unless you whitelist them or share an audience.
- Second-party categories: Private categories that another DMP partner has shared with you using one of the following methods:
- Whitelisting: A data provider can share a category in their private taxonomy with you so that you can target, analyze, and model users in that category. A DMP client typically whitelists their consumer data so that another DMP client can use it for some mutually beneficial activation. Categories can be whitelisted using the taxonomy partner permissions API or the taxonomy sharing tool in the Oracle Data Cloud platform.
- Audience sharing: A DMP partner can share an audience with you so that you can create a campaign with that audience or analyze the audience. DMP clients typically share their audiences with an agency who will run a campaign for them. You can use the audience grant API or the audience management tool in the Oracle Data Cloud platform UI to share audiences.
- Third-party categories: Categories in the Oracle Data Marketplace available to all DMP partners
How do I use the categories API to understand the user data I receive from Oracle Data Cloud ?
When you receive Oracle Data Cloud platform data, you can use the categories API to determine which category you have received and who owns the data. For example, if you receive a campaign with category ID 6737
, you could use the categories API to see that the category ID means In-Market > Autos > Makes & Models > Chevrolet > Camaro and the data is owned by the platform..
When do I use the categories API?
- Data discovery: You can use the categories API to get more information on the categories you have received:
- First-party categories: If you are a DMP client, you can use the categories API to get the first-party categories in your private taxonomy and view your inventory of unique users in each category.
- Third-party categories: If you are a data buyer, you can use the categories API to view the third-party categories and inventory in the Oracle Data Marketplace.
- Audience analytics: If you are a data app partner who is programmatically running audience analytics, you can call the categories API and use the returned categories as the input for your calls to the audience discovery Report - multi audience API.
- Data delivery configuration: You can use the categories API to configure your system to display and receive user data:
- User interface: If you are a data app partner, you can use the categories API to display third-party categories in your own UI.
- Data mapping: If you are a data app partner, you can use the categories API to map categories to your third-party audience targeting segments. Call the categories API daily to maintain your category-segment mapping.
- Data delivery: Use the categories API to deliver user data:
- Create audiences and campaigns: If you are a data app partner programmatically creating audiences and campaigns, you must call the categories API first and use the returned categories as the input for your calls to the audiences and campaigns APIs.
- Data delivery method: The manner in which categories are transferred to you depends on the data delivery method:
- If you are receiving data via server data transfer (SDT), the category ID is included in the JSON-formatted data (POST), URL (GET), or file (batch) returned to you.
- If you are receiving data via an image pixel, the pixel must include the
$CATEGORIES
macro for you to receive category IDs. - If you are receiving data via a JSON return, the category ID is included in the invisible
bk_results
object that is returned to your web page. - If you are receiving data via the user data API, the category ID is included in the JSON-formatted data returned to you after a successful request.
Related API calls
Here are the API calls you will typically make after you use the categories API:
Post-categories API | Use case |
---|---|
Audiences API | Use categories to create the audience you want to target, model, optimize, or analyze. |
Campaigns API | Create instructions for delivering your audience to a partner. |
Segment reach API | Get the reach (estimated number of unique users) for the individual categories and segments in your audience. |
Taxonomy partner permissions API | Share or withhold access to your first-party categories. |