Taxonomy API

You can implement the Oracle Data Cloud taxonomy web service to get everything you need to know about categories, which represent groups of users. For example, a category named "In-Market > Smartphone" would represent all the users who have demonstrated intent to buy a smartphone. All the individual categories are organized and listed in the taxonomy, which is a single hierarchical tree structure. You can then select categories from the taxonomy to build target audiences. To do this, you group the categories into segments using OR logic, and then include and exclude individual segments using AND or NAND logic (see the audience API for more information on creating audiences).

Important: This is the Oracle Data Cloud platform's old taxonomy API, which will be replaced by the new categories REST API. You should migrate to the new API to benefit from its additional parameters and be ready once the old API is discontinued.

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.

taxonomy6.docs.apiary.io/

For help with this API, contact My Oracle Support (MOS).

Service URI

The URI for the taxonomy API is:

services.bluekai.com/Services/WS/Taxonomy

Taxonomy API use cases

What type of data does the taxonomy API provide?

  • First-party categories: Categories in your private first-party taxonomy. These categories are only available in your DMP.
  • 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 permissioning 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. 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.
  • Third-party categories: Categories in the Oracle Data Marketplace. These categories are available to all DMP partners.

How do I use the taxonomy API to understand the user data I receive from the platform?

When you receive Oracle Data Cloud platform data, you can use the taxonomy 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 taxonomy API to see that the category ID means In-Market > Autos > Makes & Model > Chevrolet > Camaro and the data is owned by Oracle Data Cloud. You could also use the taxonomy API to see that category ID 14835 is B2B > Bizo (Business Data) > Functional Area > C-Suite and the data is owned by Bizo.

When do I use the taxonomy API?

  • Data discovery: You can use the taxonomy API to get more information on the categories you have received:
    • First-party categories: If you are a DMP client, you can use the taxonomy 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 taxonomy 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 taxonomy 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 taxonomy API to configure your system to display and receive user data:
    • User interface: If you are an Oracle Data Cloud platform data app partner, you can use the taxonomy API to display the third-party categories in the platform taxonomy in your own user interface.
    • Data mapping: If you are Oracle Data Cloud platform data app partner, you can use the taxonomy API to map categories to your third-party audience targeting segments. Call the taxonomy API daily to maintain an updated category-segment mapping.
  • Data delivery: You can use the taxonomy API to deliver user data.
    • Create audience and campaigns: If you are a data app partner programmatically creating audiences and campaigns, you must call the taxonomy API first and use the returned categories as the input for your calls to the audience API and campaign API, respectively.
    • 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.

How do I filter out country categories IDs that appear in my SDT data?

You can use the countries API to get the country codes and corresponding category IDs, use this list to programmatically filter out the country category IDs in your SDT data, and then pass the filtered list to the taxonomy API.

Related API calls

Here are the API calls you will typically make after you use the taxonomy API:

Post-taxonomy API Use case
Audiences API Create the audience you want to target, model, optimize, or analyze.
Campaigns API Create instructions for delivering your audience to DMP partner.
Segment reach API Get the estimated number of unique users in a category, segment, and audience before delivering the audience.

GET response summary

The taxonomy API request returns a NodeList object containing a list of categories. Here are the default properties included for each category:

Property Type Description
nodeID integer The unique ID assigned to the category
nodeName string The name of the category node
To get the full taxonomy path for the category, enable the FullTaxonomyPath parameter.
parentID string The unique ID assigned to the category's parent node

Note: The GET response time may vary based on the number of categories being returned and the specified options. Specifically, if you enable the bkSize parameter to include the inventory figures with the categories being returned, the taxonomy API response time may increase to a few minutes.

Learn more

Categories API