Overview

The EIQI taxonomy is the organization of the segment catalogue in a hierarchy, starting with broad categories and moving to more specific subcategories. To the user selecting the segments for targeting, the taxonomy (hierarchy) is presented in the form of a tree, where the user can expand branches to reveal and select the segments for targeting.

The process of uploading a taxonomy involves the following steps:

• Retrieve segment types
• Upload taxonomy
• Taxonomy review by EIQI team
• Check taxonomy upload status and retrieve taxonomy

Once the taxonomy is uploaded successfully, the segments become available for targeting of insertions, deals and line items In Equativ’s EMP/Maestro user interfaces, etc.

Step 1 - Retrieve segment types

First, retrieve all segment types to ensure the segment types you plan to upload already exist in the system. The segment type is at the top level in the segment hierarchy (segment tree). For instance, in the screenshot in section “Overview “ above, the “Contextual” node is a segment type.

A segment itself represents a pool of URLs or BundleIDs that share a common characteristic. Any segment you upload must be associated with a segment type that exists in Equativ’s system.

Use the GET /taxonomy/segment-types endpoint to retrieve a list of available segment types from the EIQI API, such as “Seasonal”,” Language”, etc. The segment types are intended for use in the type field when uploading the taxonomy (see type field in table under “Taxonomy upload fields” below).

Example curl command to retrieve segment types

curl --location'https://eiqi.eqtv.io/api/v2/contextual/taxonomy/segment-types' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 1124111|b1xJXLKPFfJN832QO6SamsvTZuaWdA0hIeTDnJ1cfefa65b5' \

Step 2 - Upload taxonomy

To upload the taxonomy (as a .json, .csv or .xlsx file), use the POST api/v2/contextual/taxonomy/upload endpoint, making sure you comply with the rules explained in the table “Taxonomy upload fields” below.

Warnings

• Any violation of the rules explained in the table “Taxonomy upload fields” below leads to the entire upload being rejected.
• Each time you upload the taxonomy, a complete refresh occurs: new segments are not added to the existing data but the entire previous taxonomy is cleared out and replaced with the new version. Therefore, always ensure that your new taxonomy includes all necessary data.

Example curl command to upload taxonomy

curl --location 'https://eiqi.eqtv.io/api/v2/contextual/taxonomy/upload' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 1124111|b1xJXLKPFfJN832QO6SamsvTZuaWdA0hIeTDnJ1cfefa65b5' \
--data '{

     "data": [
            {
                 "parent_id": null,
                 "type": "Standard",
                 "id": "My segment id",
                 "name": "My segment name",
                 "display_name": "My display name",
                 "description": "My description",
                 "is_exclusion": false,
                 "is_selectable": true,
                 "is_custom": false,
                 "price": 12.45,
                 "currency": "EUR",
                 "provider_name": "My provider name",
                 "provider_source": "My provider source",
                 "is_active": true
            }
       ]
}'

Step 3 - Taxonomy review by EIQI team

Any taxonomy upload triggers a review notification to Equativ’s EIQI team. Once reviewed (usually within 24 to 48 hours), the new taxonomy is returned in the GET /contextual/taxonomy endpoint, as described in Step 4 below: “Check taxonomy upload status and retrieve taxonomy". Segments become available in Equativ’s platforms for targeting within 12 hours following the review.

The step “Taxonomy review by EIQI team” step can be removed from the process, if the data provider feels confident to upload taxonomies without any review or assistance by the EIQI team.

Step 4 - Check taxonomy upload status and retrieve taxonomy

Use the GET /api/v2/contextual/taxonomy endpoint to check the status of your taxonomy upload and to retrieve the uploaded taxonomy.

Remember that there is no automatic notification to inform you when the review process is complete.

Example of a segment from a retrieved taxonomy

{
   "ctx_equativ_semantic": [
     {
        "id": "100001",
        "parent_id": null,
        "type": "Standard",
        "type_id": 4,
        "name": "Agriculture & Farming",
        "display_name": "Agriculture & Farming",
        "description": null,
        "is_exclusion": false,
        "is_selectable": true,
        "is_custom": false,
        "price": 0.2,
        "currency": "EUR",
        "provider_name": null,
        "provider_source": null,
        "is_active": true,
        "data_source": "ctx_equativ_semantic"
    },

Taxonomy upload fields

The table below presents the fields required for EIQI taxonomy data upload.