Skip to content

Categories

Category properties

Document classification returns categories drawn from the specified taxonomy.

You can get the list of categories identified by each document classification resource by requesting the corresponding API self-documentation resource.

Each category has two explicit properties, id and label. id is the identifying code, label is the description.

Each category also has an implicit property which is its path within the taxonomy. The path is the sequence of categories that goes from the farthest ancestor to the category itself. For example, the path of the American black bear inside the animal kingdom "category tree" is:

Eukarya
    Animalia
        Chordata
            Mammalia
                Carnivora
                    Ursidae
                        Ursus
                            Ursus americanus

If the category tree is flat—it has only one hierarchical level—the path coincides with the category itself.
In the classification output, the path is returned in the hierarchy property. It is an array containing the values of the label property for all the categories along the path.

Categories having the same value for the id property in different language versions of the same taxonomy are conceptually the same. For example, in the different versions of the geotax taxonomy for the five supported languages, the category for Cambodia has the same value for id, but different values for label:

iptc taxonomy

The properties of the categories of the iptc taxonomy reflect those of the Media Topics taxonomy. In particular, the id property corresponds to the numeric part of the Media Topics subject code, while the label property corresponds to its name. As mentioned above, the labels vary by language.

Use the self-documentation resources to get the complete list of recognized categories.

geotax taxonomy

The categories of the geotax taxonomy correspond to all countries of the world.
In the particular cases of United States of America and United Kingdom there are also categories corresponding to the different states or countries that make up the federation or kingdom. For example, there is both a category for the United Kingdom (id = 184.) and one for Wales (id = 18404.).
In such cases, in the category tree the categories corresponding to member countries are nested by a level, that is, they are "children" of the categories corresponding to the federation or kingdom. for example:

United Kingdom
    England
    Northern Ireland
    Scotland
    Wales

All categories of the tree can be output. So for example in the case of this input text:

He was born in 1930 in Cardiff.

the output will be:

id label
184. United Kingdom
18404. Wales

As mentioned above, the labels of the categories vary by language.

Always use the self-documentation resources to get the complete list of recognized categories.

emotional-traits taxonomy

This is the emotional-traits taxonomy's category tree:

Group Rage
    Anger
    Irritation
    Exasperation
Group Apprehension
    Anxiety
    Fear
    Stress
    Worry
Group Distress
    Disgust
    Repulsion
    Guilt
    Shame
    Embarrassment
    Regret
    Boredom
Group Resentment
    Hatred
    Offence
    Jealousy
    Envy
Group Dejection
    Sadness
    Torment
    Suffering
    Disappointment
    Disillusion
    Resignation
Group Surprise
    Surprise
Group Delight
    Happiness
    Excitement
    Joy
    Amusement
    Well-Being
    Satisfaction
    Relief
Group Fondness
    Like
    Trust
    Affection
    Love
    Passion
    Empathy
    Compassion

The categories that can be returned in output—the recognized emotional traits—are only those at the 2nd level of the hierarchy, the "leaves" of the tree.
The 1st level categories function as groups. The information of the group an emotion belongs to is available in output in the hierarchy property, which represents the full path of the output category inside the tree.
For example:

...
"frequency": 50.26,
"hierarchy": [
    "Group Delight",
    "Amusement"
],
"id": "0704",
"label": "Amusement"
...

It is also possible to get the main groups as an additional output.

behavioral-traits taxonomy

The behavioral-traits taxonomy categories are:

Sociality
    Sociality low
        Asociality
        Impoliteness
        Ungratefulness
        Emotionality
        Isolation
        Disagreement
    Sociality fair
        Seriousness
        Introversion
        Unreservedness
        Humour
        Sexuality
    Sociality high
        Extroversion
        Pleasantness
        Trustfulness
        Gratefulness
        Empathy
Action
    Action low
        Sedentariness
        Passivity
    Action fair
        Calmness
    Action high
        Initiative
        Dynamism
Openness
    Openness low
        Rejection
        Apathy
        Apprehension
        Traditionalism
        Conformism
        Negativity
        Bias
    Openness fair
        Cautiousness
    Openness high
        Progressiveness
        Acceptance
        Courage
        Positivity
        Curiosity
Consciousness
    Consciousness low
        Superficiality
        Unawareness
        Disorganization
        Insecurity
        Ignorance
        Illusion
    Consciousness high
        Awareness
        Spirituality
        Concern
        Knowledge
        Self-confidence
        Organization
Ethics
    Ethics low
        Violence
        Extremism
        Discrimination
        Dishonesty
        Neglect
        Unlawfulness
        Irresponsibility
    Ethics high
        Honesty
        Compassion
        Commitment
        Lawfulness
        Solidarity
        Inclusiveness
Capability
    Capability low
        Lack of intelligence
        Inexperience
        Incompetence
    Capability fair
        Rationality
    Capability high
        Smartness
        Creativity
        Competence
Moderation
    Moderation low
        Dissoluteness
        Gluttony
        Materialism
        Addiction
    Moderation fair
        Healthy lifestyle
    Moderation high
        Self-restraint

The categories that can be returned in output—the recognized behavioral traits—are only those at the 3rd level of the hierarchy, the "leaves" of the tree.
The 1st and 2nd level categories are used to group the other. The information of the group and sub-group a personality trait belongs to is available in output in the hierarchy property, which represents the full path of the output category inside the tree.
For example:

...
"frequency": 75.25,
"hierarchy": [
    "Moderation",
    "Moderation low",
    "Gluttony"
],
"id": "7102",
"label": "Gluttony"
...