Taxonomy

Taxonomy in DataX is represented by a JSON structure.

Using a JSON structure, you can establish a single Taxonomy for all your syndicated/custom/ad-hoc segments/audiences, raw attributes, advertiser specific data, region specific data, and so, organized in a flat or a hierarchical manner (with a maximum depth 20).

Important

You must export a snapshot of the taxonomy prior to sending any user data. This helps Yahoo Ad Tech understand your IDs and your data’s logical grouping as you see it.

Node Types

A node (taxonomy element) in the taxonomy can be one of the following three types:

1. “SEGMENT” (binary qualifications/activity against predefined criteria/actions), or 2. “ATTRIBUTE” (raw values for a user as defined in the terminology table above). 3. A placeholder element used as parent of another element.

Sample Taxonomy

[{"name":"Retail Segments","type":"SEGMENT","subTaxonomy":[
{"name":"Children's Product Buyers", "subTaxonomy":[
{"name":"Baby Products","id":"OH10"},
{"name":"Toys","id":"OH22"}
]},

{"name":"Home Improvement","subTaxonomy":[
{"name":"Organization","id":"OH13"},
{"name":"Home Depot DIY Tools","users":{"include":["9873"]},"id":"OH9"}
]}
]},

{"name":"Supplimental Data", "type":"ATTRIBUTE","subTaxonomy":[
{"name":"Age","id":"MA1", "attributeDef":{"type":"number","values":["18|100"]}},
{"name":"Spend","id":"MA2", "attributeDef":{"type":"number","values":["1|10000"]}},
{"name":"Women's Style","id":"MA3", "attributeDef":{"type":"enum","values":["Modern","Traditional"]}}
]}]

Data Categorization

Data is categorized as a segment or an attribute via a “type”. A segment or an attribute is made advertiser-specific by assigning properties such as “users” to the taxonomy element. The Grouping/Hierarchy is established by nesting taxonomy elements via the subTaxonomy tag.

The JSON tags above have been intentionally hand-formatted in a way that also provides a compact visual representation of the Taxonomy arrangement. Though it does not need to be printed this way when generated programmatically, you may find the above representation easy to edit manually for small pilots and initial sandbox integration.

See also:

Example: Post a taxonomy using curl

This is how a partner “YaRetail” would upload a two-level segment and attribute taxonomy, using the DataX API & curl as a command line HTTP client.

curl -X POST -H "Content-Type: multipart/form-data" \
-F 'metadata={"description":"YaRetail Taxonomy"}' \
-F 'data=@yahooTaxonomy.json;type=application/json' \ datax.yahooapis.com/v1/taxonomy

Where: yahooTaxonomy.json may have the following contents:

[
{"name":"Syndicated Segments","type":"SEGMENT","subTaxonomy":[
{"name":"Baby Product Buyers","id":"YA1"},
{"name":"New Car Buyers","id":"YA2"},
{"name":"Home Improvement","subTaxonomy":[
{"name":"DIY","id":"YA3"},
{"name":"Decorative","id" : "YA4"}
]}
]},
{"name":"1st Party","type":"ATTRIBUTE","subTaxonomy":[
{"name":"Age","id":"MA1", "attributeDef":{"type":"number","values":["18|100"]}},
{"name":"Spend","id":"MA2", "attributeDef":{"type":"number","values":["1|10000"]}},
{"name":"Style","id":"MA3", "attributeDef":{"type":"enum","values":["Modern","Traditional","Ethnic"]}}
]}
]

DataX will send back a 202 Accepted response with the following sample MetaData+ in JSON:

{
        "resourceType" : "datax-taxonomy",
        "resourceId" : "130815T013759Z662589033",
        "createTime" : "2013-14-05T17:47:32Z",
        "description" : "YaRetail Taxonomy",
        "links" : [{
                "rel"   : "self",
                "href" : "https://datax.yahooapis.com/v1/link/s/ozQ8sfE9ffoJgj7tGEJV-"
        },{
                "rel"   : "describes",
                "href" : "https://datax.yahooapis.com/v1/link/rw5fasr4akqoawjrtkhaQ-"
        }],
        "status" : {
                "state" : "PROCESSING",
                "lastUpdateTime" : "2013-14-05T17:47:32Z"
        }
}

You could use the “self” link to re-fetch this metadata for an updated status. The metadata structure also provides an error list on failure, not shown in this example.