Creating Categories
Adding a new Category to your Project.
Creating a Category
The following call will create a new Category called "Test Category", with subcategories "Example Subcategory 1" and "Example Subcategory 2" in the Project with the id 162752818:
(Click here to learn how to get your Project ID)
curl -X POST 'https://api.brandwatch.com/projects/162752818/rulecategories' \
-H 'Content-Type: application/json' \
-d '{
"children": [
{
"name": "Test Subcategory - Chocolate"
},
{
"name": "Test Subcategory - Vanilla"
}
],
"multiple": true,
"name": "Test Category - Ice Cream Flavors"
}'
This will return the following response:
{
"id": 14811173,
"name": "Test Category - Ice Cream Flavors",
"displayName": null,
"multiple": true,
"queryIds": null,
"children": [
{
"id": 14811174,
"name": "Test Subcategory - Chocolate",
"ordering": 1,
"rules": []
},
{
"id": 14811175,
"name": "Test Subcategory - Vanilla",
"ordering": 2,
"rules": []
}
],
"matchingType": "manual"
}
Creating a Category with Searches and Filters
This endpoint also allows you to define searches and filters to automatically perform actions on mentions, both in the future and historically. For example, you may set up a Category that automatically applies a Subcategory with the name "Purchase" when the text of the Mention contains the phrase "I just bought".
The following example creates a parent Category "Test Category - Ice Cream Flavors" and 2 children Categories: the first one is named "Test Subcategory - Chocolate" and searches and filters are used to segment Mentions into that subcategory that meet the criteria under "filter", namely Mentions which include the phrase chocolate, are classified as positive sentiment and which come from USA. Additionally, Mentions with a location of DEU (Germany) are excluded. The second subcategory is named "Test Subcategory - Vanilla" and searches and filters are used to segment Mentions into that subcategory that include the phrase vanilla and with an identified language as English, whereas Mentions with an identified language as German are excluded.
curl -X POST 'https://api.brandwatch.com/projects/1998283571/rulecategories' \
-H 'Content-Type: application/json' \
-d '{
"children": [
{
"name": "Test Subcategory - Chocolate",
"rules": [
{
"filter": {
"search": "chocolate",
"sentiment": [
"positive"
],
"location": [
"USA.PA"
],
"xlocation": [
"DEU"
]
}
}
]
},
{
"name": "Test Subcategory - Vanilla",
"rules": [
{
"filter": {
"search": "vanilla",
"language": [
"en"
],
"xlanguage": [
"de"
]
}
}
]
}
],
"multiple": true,
"name": "Test Category - Ice Cream Flavors"
}'
The response will look like this:
{
"id": 15483261,
"name": "Test Category - Ice Cream Flavors",
"displayName": null,
"multiple": true,
"queryIds": null,
"children": [
{
"id": 15483262,
"name": "Test Subcategory - Chocolate",
"ordering": 1,
"rules": [
{
"id": 162563587,
"projectId": null,
"name": null,
"filter": {
"queryId": null,
"queryGroupId": null,
"projectId": null,
"startDate": null,
"endDate": null,
"timezone": null,
"search": "chocolate",
"sinceAssignmentUpdated": null,
"untilAssignmentUpdated": null,
"author": null,
"xauthor": null,
"exactAuthor": null,
"xexactAuthor": null,
"authorGroup": null,
"xauthorGroup": null,
"sentiment": [
"positive"
],
"pageType": null,
"xpageType": null,
"siteGroup": null,
"xsiteGroup": null,
"locationGroup": null,
"xlocationGroup": null,
"location": [
"USA.PA"
],
"xlocation": [
"DEU"
],
"category": null,
"xcategory": null,
"parentCategory": null,
"xparentCategory": null,
"tag": null,
"xtag": null,
"anyTag": null,
"status": null,
"xstatus": null,
"priority": null,
"xpriority": null,
"checked": null,
"starred": null,
"assigned": null,
"xassigned": null,
"monthlyVisitorsMax": null,
"monthlyVisitorsMin": null,
"twitterFollowersMax": null,
"twitterFollowersMin": null,
"twitterFollowingMax": null,
"twitterFollowingMin": null,
"twitterReplyTo": null,
"xtwitterReplyTo": null,
"twitterRetweetOf": null,
"xtwitterRetweetOf": null,
"twitterPostCountMax": null,
"twitterPostCountMin": null,
"twitterRetweetsMax": null,
"twitterRetweetsMin": null,
"reachEstimateMin": null,
"reachEstimateMax": null,
"language": null,
"xlanguage": null,
"domain": null,
"xdomain": null,
"facebookAuthorId": null,
"xfacebookAuthorId": null,
"facebookRole": null,
"xfacebookRole": null,
"facebookSubtype": null,
"xfacebookSubtype": null,
"subtype": null,
"xsubtype": null,
"facebookCommentsMax": null,
"facebookCommentsMin": null,
"facebookLikesMax": null,
"facebookLikesMin": null,
"facebookSharesMax": null,
"facebookSharesMin": null,
"twitterVerified": null,
"twitterRole": null,
"twitterAuthorId": null,
"xtwitterAuthorId": null,
"impressionsMax": null,
"impressionsMin": null,
"impactMax": null,
"impactMin": null,
"instagramFollowersMax": null,
"instagramFollowersMin": null,
"instagramFollowingMax": null,
"instagramFollowingMin": null,
"instagramPostsMax": null,
"instagramPostsMin": null,
"instagramLikesMax": null,
"instagramLikesMin": null,
"instagramCommentsMax": null,
"instagramCommentsMin": null,
"instagramInteractionsMax": null,
"instagramInteractionsMin": null,
"threadId": null,
"xthreadId": null,
"threadEntryType": null,
"xthreadEntryType": null,
"threadAuthor": null,
"xthreadAuthor": null,
"postByAuthor": null,
"xpostByAuthor": null,
"shareOfAuthor": null,
"xshareOfAuthor": null,
"replyToAuthor": null,
"xreplyToAuthor": null,
"resourceType": null,
"xresourceType": null,
"insightsEmoticon": null,
"insightsEmoji": null,
"insightsHashtag": null,
"insightsMentioned": null,
"insightsUrl": null,
"insightsSharedSite": null,
"xinsightsEmoticon": null,
"xinsightsEmoji": null,
"xinsightsHashtag": null,
"xinsightsMentioned": null,
"xinsightsUrl": null,
"xinsightsSharedSite": null,
"gender": null,
"accountType": null,
"profession": null,
"xprofession": null,
"interest": null,
"xinterest": null,
"exclusiveLocation": null,
"hourOfDay": null,
"dayOfWeek": null,
"geolocated": null,
"latitudeMin": null,
"latitudeMax": null,
"longitudeMin": null,
"longitudeMax": null,
"logoImagesGroupId": null,
"xlogoVersions": null,
"logoVersions": null,
"xclassifications": null,
"classifications": null,
"youtubeOnly": null,
"audienceList": null,
"xaudienceList": null
},
"scope": null,
"enabled": true,
"ruleAction": null,
"queryName": null,
"projectName": "Segmentation IA Test",
"categoryId": 15483262,
"queryIds": null
}
]
},
{
"id": 15483263,
"name": "Test Subcategory - Vanilla",
"ordering": 2,
"rules": [
{
"id": 162563588,
"projectId": null,
"name": null,
"filter": {
"queryId": null,
"queryGroupId": null,
"projectId": null,
"startDate": null,
"endDate": null,
"timezone": null,
"search": "vanilla",
"sinceAssignmentUpdated": null,
"untilAssignmentUpdated": null,
"author": null,
"xauthor": null,
"exactAuthor": null,
"xexactAuthor": null,
"authorGroup": null,
"xauthorGroup": null,
"sentiment": null,
"pageType": null,
"xpageType": null,
"siteGroup": null,
"xsiteGroup": null,
"locationGroup": null,
"xlocationGroup": null,
"location": null,
"xlocation": null,
"category": null,
"xcategory": null,
"parentCategory": null,
"xparentCategory": null,
"tag": null,
"xtag": null,
"anyTag": null,
"status": null,
"xstatus": null,
"priority": null,
"xpriority": null,
"checked": null,
"starred": null,
"assigned": null,
"xassigned": null,
"monthlyVisitorsMax": null,
"monthlyVisitorsMin": null,
"twitterFollowersMax": null,
"twitterFollowersMin": null,
"twitterFollowingMax": null,
"twitterFollowingMin": null,
"twitterReplyTo": null,
"xtwitterReplyTo": null,
"twitterRetweetOf": null,
"xtwitterRetweetOf": null,
"twitterPostCountMax": null,
"twitterPostCountMin": null,
"twitterRetweetsMax": null,
"twitterRetweetsMin": null,
"reachEstimateMin": null,
"reachEstimateMax": null,
"language": [
"en"
],
"xlanguage": [
"de"
],
"domain": null,
"xdomain": null,
"facebookAuthorId": null,
"xfacebookAuthorId": null,
"facebookRole": null,
"xfacebookRole": null,
"facebookSubtype": null,
"xfacebookSubtype": null,
"subtype": null,
"xsubtype": null,
"facebookCommentsMax": null,
"facebookCommentsMin": null,
"facebookLikesMax": null,
"facebookLikesMin": null,
"facebookSharesMax": null,
"facebookSharesMin": null,
"twitterVerified": null,
"twitterRole": null,
"twitterAuthorId": null,
"xtwitterAuthorId": null,
"impressionsMax": null,
"impressionsMin": null,
"impactMax": null,
"impactMin": null,
"instagramFollowersMax": null,
"instagramFollowersMin": null,
"instagramFollowingMax": null,
"instagramFollowingMin": null,
"instagramPostsMax": null,
"instagramPostsMin": null,
"instagramLikesMax": null,
"instagramLikesMin": null,
"instagramCommentsMax": null,
"instagramCommentsMin": null,
"instagramInteractionsMax": null,
"instagramInteractionsMin": null,
"threadId": null,
"xthreadId": null,
"threadEntryType": null,
"xthreadEntryType": null,
"threadAuthor": null,
"xthreadAuthor": null,
"postByAuthor": null,
"xpostByAuthor": null,
"shareOfAuthor": null,
"xshareOfAuthor": null,
"replyToAuthor": null,
"xreplyToAuthor": null,
"resourceType": null,
"xresourceType": null,
"insightsEmoticon": null,
"insightsEmoji": null,
"insightsHashtag": null,
"insightsMentioned": null,
"insightsUrl": null,
"insightsSharedSite": null,
"xinsightsEmoticon": null,
"xinsightsEmoji": null,
"xinsightsHashtag": null,
"xinsightsMentioned": null,
"xinsightsUrl": null,
"xinsightsSharedSite": null,
"gender": null,
"accountType": null,
"profession": null,
"xprofession": null,
"interest": null,
"xinterest": null,
"exclusiveLocation": null,
"hourOfDay": null,
"dayOfWeek": null,
"geolocated": null,
"latitudeMin": null,
"latitudeMax": null,
"longitudeMin": null,
"longitudeMax": null,
"logoImagesGroupId": null,
"xlogoVersions": null,
"logoVersions": null,
"xclassifications": null,
"classifications": null,
"youtubeOnly": null,
"audienceList": null,
"xaudienceList": null
},
"scope": null,
"enabled": true,
"ruleAction": null,
"queryName": null,
"projectName": "Segmentation IA Test",
"categoryId": 15483263,
"queryIds": null
}
]
}
],
"matchingType": "keywords"
}
You can now use these Category and Subcategory IDs when filtering or breaking down Mention calls. Elsewhere in the documentation you may see the top-level Categories being referred to as "Parent Categories".
In order to categorize existing (historical) Mentions, you must make a separate API call.
In the following example, 15483261 is the Category id from the response above.
curl -X POST 'https://api.brandwatch.com/projects/162752818/bulkactions/rulecategories/15483261?earliest=2018-06-01'
Updated over 1 year ago