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

These are the emotional-traits taxonomy category trees:

id      label (English)     label (German)

0100    Group Rage          Gruppe Ärger
0101        Anger               Wut
0102        Irritation          Gereiztheit
0103        Exasperation        Außersichsein
0200    Group Apprehension  Gruppe Befürchtung
0202        Anxiety             Angst
0203        Fear                Furcht
0204        Stress              Stress
0205        Worry               Sorge
0300    Group Distress      Gruppe Unbehagen
0301        Disgust             Ekel
0302        Repulsion
0311        Guilt               Schuldgefühl
0312        Shame               Scham
0313        Embarrassment       Verlegenheit
0322        Regret              Bedauern
0331        Boredom             Langeweile
0400    Group Resentment    Gruppe Groll
0402        Hatred              Hass
0403        Offence             Beileidigung
0411        Jealousy            Eifersucht
0412        Envy                Neid
0500    Group Dejection     Gruppe Niedergeschlagenheit
0501        Sadness             Traurigkeit
0502        Torment
0503        Suffering           Leiden
0511        Disappointment      Enttäuschung
0512        Disillusion
0513        Resignation         Resignation
0600    Group Surprise      Gruppe Überraschung
0601        Surprise            Überraschung
0700    Group Delight       Gruppe Vergnügen
0701        Happiness           Freude
0702        Excitement          Begeisterung
0703        Joy
0704        Amusement           Belustigung
0705        Well-Being          Wohlsein
0711        Satisfaction        Zufriedenheit
0721        Relief              Erleichterung
0800    Group Fondness      Gruppe Sympathie
0801        Like                Mögen
0802        Trust               Vertrauen
0803        Affection           Zuneigung
0804        Love                Liebe
0805        Passion             Leidenschaft
0812        Empathy             Einfühlung
0813        Compassion          Mitgefühl

Note

You may notice that some categories in the tree for English do not have a correspondent in the tree for German.
The reason is that in German the distinction between some categories is not as clear as in English, so it was chosen to collapse similar categories:

  • 0301 and 0302 → 0301
  • 0501 and 0502 → 0501
  • 0511 and 0512 → 0511
  • 0701 and 0703 → 0701.

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:

id      label (English)             label (German)

1000    Sociality                   Geselligkeit        
1100        Sociality low               Geselligkeit niedrig    
1101            Asociality                  Ungeselligkeit
1102            Impoliteness                Unhöflichkeit
1103            Ungratefulness              Undankbarkeit
1104            Emotionality                Empfindlichkeit
1105            Isolation                   Vereinsamung
1106            Disagreement                Meinungsverschiedenheit
1200        Sociality fair              Geselligkeit fair   
1201            Seriousness                 Ernsthaftigkeit
1202            Introversion                Introvertiertheit
1203            Unreservedness              Unverblümtheit
1204            Humour                      Humor
1205            Sexuality                   Sexualität
1300        Sociality high              Geselligkeit hoch   
1301            Extroversion                Extravertiertheit
1302            Pleasantness                Freundlichkeit
1303            Trustfulness                Zutraulichkeit
1304            Gratefulness                Dankbarkeit
1305            Empathy                     Einfühlung
2000    Action                      Aktivität       
2100        Action low                  Aktivität niedrig   
2101            Sedentariness               Faulheit
2102            Passivity                   Passivität
2200        Action fair                 Aktivität fair  
2201            Calmness                    Gelassenheit
2300        Action high                 Aktivität hoch  
2301            Initiative                  Tatendrang
2302            Dynamism                    Tatkraft
3000    Openness                    Aufgeschlossenheit      
3100        Openness low                Aufgeschlossenheit niedrig  
3101            Rejection                   Ablehnung
3102            Apathy                      Gleichgültigkeit
3103            Apprehension                Besorgtheit
3104            Traditionalism              Traditionalismus
3105            Conformism                  Konformismus
3106            Negativity                  Pessimismus
3107            Bias                        Voreingenommenheit
3200        Openness fair               Aufgeschlossenheit fair 
3201            Cautiousness                Vorsichtigkeit
3300        Openness high               Aufgeschlossenheit hoch 
3301            Progressiveness             Fortschrittlichkeit
3302            Acceptance                  Akzeptanz
3303            Courage                     Mut
3304            Positivity                  Optimismus
3305            Curiosity                   Neugier
4000    Consciousness               Bewusstheit     
4100        Consciousness low           Bewusstheit niedrig 
4101            Superficiality              Oberflächlichkeit
4102            Unawareness                 Unwissenheit
4103            Disorganization             Unordnung
4104            Insecurity                  Verunsicherung
4105            Ignorance                   Ignoranz
4106            Illusion                    Illusion
4300        Consciousness high          Bewusstheit hoch    
4301            Awareness                   Bewusstsein
4302            Spirituality                Spiritualität
4303            Concern                     Besorgnis
4304            Knowledge                   Kenntnis
4305            Self-confidence             Selbstbewusstsein
4306            Organization                Ordnung
5000    Ethics                      Ethik       
5100        Ethics low                  Ethik niedrig   
5101            Violence                    Gewalttätigkeit
5102            Extremism                   Extremismus
5103            Discrimination              Diskriminierung
5104            Dishonesty                  Unehrlichkeit
5105            Neglect                     Vernachlässigung
5106            Unlawfulness                Ungesetzlichkeit
5107            Irresponsibility            Verantwortungslosigkeit
5300        Ethics high                 Ethik hoch  
5301            Inclusiveness               Inklusion
5302            Honesty                     Ehrlichkeit
5303            Compassion                  Mitgefühl
5304            Commitment                  Engagement
5305            Lawfulness                  Gesetzlichkeit
5306            Solidarity                  Solidarität
6000    Capability                  Leistungsvermögen       
6100        Capability low              Leistungsvermögen niedrig   
6101            Lack of intelligence        Einfältigkeit
6102            Inexperience                Unerfahrenheit
6103            Incompetence                Unfähigkeit
6200        Capability fair             Leistungsvermögen fair  
6201            Rationality                 Vernünftigkeit
6300        Capability high                 Leistungsvermögen hoch  
6301            Smartness                   Klugheit
6302            Creativity                  Kreativität
6303            Competence                  Kompetenz
7000    Moderation                  Konsumverhalten     
7100        Moderation low              Konsumverhalten niedrig 
7101            Dissoluteness               Ausschweifung
7102            Gluttony                    Essgier
7103            Materialism                 Materialismus
7104            Addiction                   Sucht
7200        Moderation fair             Konsumverhalten fair    
7201            Healthy lifestyle           Gesunde Lebensweise
7300        Moderation high             Konsumverhalten hoch    
7301            Self-restraint              Selbstbeherrschung

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"
...