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)

300     Group Distress      Gruppe Unbehagen
301         Disgust             Ekel
302         Repulsion
311         Guilt               Schuldgefühl
312         Shame               Scham
313         Embarrassment       Verlegenheit
322         Regret              Bedauern
331         Boredom             Langeweile
400     Group Resentment    Gruppe Groll
402         Hatred              Hass
403         Offence             Beileidigung
411         Jealousy            Eifersucht
412         Envy                Neid
500     Group Dejection     Gruppe Niedergeschlagenheit
501         Sadness             Traurigkeit
502         Torment
503         Suffering           Leiden
511         Disappointment      Enttäuschung
512         Disillusion
513         Resignation         Resignation
600     Group Surprise      Gruppe Überraschung
601         Surprise            Überraschung
700     Group Delight       Gruppe Vergnügen
701         Happiness           Freude
702         Excitement          Begeisterung
703         Joy
704         Amusement           Belustigung
705         Well-Being          Wohlsein
711         Satisfaction        Zufriedenheit
721         Relief              Erleichterung
800     Group Fondness      Gruppe Sympathie
801         Like                Mögen
802         Trust               Vertrauen
803         Affection           Zuneigung
804         Love                Liebe
805         Passion             Leidenschaft
812         Empathy             Einfühlung
813         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: 301 and 302 were collapsed into 301, 501 and 502 into 501, 511 and 512 into 511 and 701 and 703 in 701.

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