Retrieving Mentions

Listing the Mentions within your Query.

Mentions are stored within Queries. There are three required parameters when retrieving Mentions:

  • queryId - The ID of the Query that contains the Mentions.
  • startDate - The beginning of the date range that contains the Mentions.
  • endDate - The end of the date range that contains the Mentions.

You can control the pagination by passing additional parameters:

  • pageSize - The number of Mentions on each page of the response.
  • page - The page to retrieve, indexed from 0.

You also have the option to control the ordering by passing additional parameters:

  • orderBy - You can order by the date of the mention ("date"), the time the mention matched your query ("added"), or the time when the mention was last updated ("updated").
  • orderDirection - Descending ("desc") or ascending ("asc").

An example call is below:

curl -X GET https://api.brandwatch.com/projects/289733322/data/mentions?queryId=348973733&startDate=2016-05-01&endDate=2016-05-02&pageSize=1&page=0

The response will look like this:

{
  "resultsTotal": 99,
  "resultsPage": 0,
  "resultsPageSize": 1,
  "results": [
    {
      "accountType": null,
      "assignment": null,
      "author": "",
      "authorCity": null,
      "authorCityCode": null,
      "authorContinent": null,
      "authorContinentCode": null,
      "authorCountry": null,
      "authorCountryCode": null,
      "authorCounty": null,
      "authorCountyCode": null,
      "authorLocation": null,
      "authorState": null,
      "authorStateCode": null,
      "avatarUrl": null,
      "averageDurationOfVisit": 0,
      "averageVisits": 0,
      "backlinks": 19,
      "blogComments": 0,
      "categories": [],
      "categoryDetails": [],
      "checked": false,
      "city": null,
      "cityCode": null,
      "continent": Europe,
      "continentCode": "eu",
      "country": "United Kingdom",
      "countryCode": "uk",
      "county": null,
      "countyCode": null,
      "date": "2016-06-07T02:04:00.000+0000",
      "displayUrls": [],
      "domain": "bbc.co.uk",
      "engagement": 0,
      "expandedUrls": [],
      "facebookAuthorId": null,
      "facebookComments": 0,
      "facebookLikes": 0,
      "facebookRole": null,
      "facebookShares": 0,
      "facebookSubtype": null,
      "forumPosts": 0,
      "forumViews": 0,
      "fullname": null,
      "gender": "unknown",
      "id": 100057070129,
      "impact": 53,
      "importanceAmplification": 76,
      "importanceReach": 31,
      "impressions": 0,
      "influence": 0,
      "insightsHashtag": [],
      "insightsMentioned": [],
      "instagramCommentCount": 0,
      "instagramFollowerCount": 0,
      "instagramFollowingCount": 0,
      "instagramLikeCount": 0,
      "instagramPostCount": 0,
      "interest": [],
      "language": "en",
      "lastAssignmentDate": null,
      "latitude": 0,
      "locationName": null,
      "longitude": 0,
      "matchPositions": [],
      "mediaUrls": [],
      "monthlyVisitors": 0,
      "mozRank": 5.87,
      "noteIds": [],
      "outreach": 0,
      "pageType": "forum",
      "pagesPerVisit": 0,
      "percentFemaleVisitors": 0,
      "percentMaleVisitors": 0,
      "priority": null,
      "professions": [],
      "queryId": 348973733,
      "queryName": "Telecoms news",
      "reach": 0,
      "replyTo": null,
      "resourceId": 100057070129,
      "resourceType": "page",
      "retweetOf": null,
      "sentiment": "neutral",
      "shortUrls": [],
      "snippet": "... known for his boisterous presentations and love of social media, said: 'Get ready for a gratitude adjustment, America. This Un-carrier move is all about giving you a good thanking! No strings. No gotchas. Just...",
      "starred": false,
      "state": null,
      "stateCode": null,
      "status": null,
      "subtype": null,
      "tags": [],
      "threadAuthor": null,
      "threadCreated": null,
      "threadEntryType": null,
      "threadId": "0",
      "threadURL": null,
      "title": "T-Mobile US customers offered free shares - BBC News",
      "trackedLinkClicks": 0,
      "trackedLinks": null,
      "twitterAuthorId": null,
      "twitterFollowers": 0,
      "twitterFollowing": 0,
      "twitterPostCount": 0,
      "twitterReplyCount": 0,
      "twitterRetweets": 0,
      "twitterRole": null,
      "twitterVerified": false,
      "url": "http://www.bbc.co.uk/news/business-36466844",
      "wordCount": null
    }
  ],
  "maximumId": 100057070129,
  "maximumIdInResult": 100057070129,
  "startDate": "2016-05-01T00:00:00.000+0000",
  "endDate": "2016-05-02T00:00:00.000+0000"
}

Encoding

The Analytics API will return data as it was found and does not apply any additional encoding or sanitization before returning it through the Mentions endpoint. It is your responsibility to make sure that it is formatted correctly for display in your own application.

Data restrictions

There are contractual obligations which may affect the metadata of the Mentions that are returned.

Data Pack restrictions

Particular Data Packs that you have added to your account may have restrictions on the Mention data that you can retrieve through the Brandwatch API. This can cause discrepancies between the data seen in the UI of the Analytics application and the data retrieved via the API. For specific information on the data packs that you have, please contact your account manager.

Twitter data

We are unable to provide the full metadata of Mentions from Twitter. Any Mention that is a tweet will have the full text and some other metadata stripped out. If you wish to include the full metadata in your own application, then we recommend registering your application with Twitter, parsing the Twitter ID from the url field, and then using the Twitter API to retrieve it.

The metadata that will be missing are as follows:

  • author
  • avatarUrl
  • date
  • displayUrls
  • expandedUrls
  • fullText
  • replyTo
  • retweetsOf
  • shortUrls
  • snippet
  • threadAuthor
  • threadEntryType
  • twitterAuthorId
  • twitterFollowers
  • twitterFollowing
  • twitterPostCount
  • twitterReplyCount
  • twitterRetweets
  • twitterRole
  • twitterVerified

Return Fields

Field
Definition
Possible Values

accountType

Account Type is the type of account ('individual' or 'organisational') that a Twitter author has. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, "individual", "organisational"

assignment

Assignment is part of the Brandwatch workflow functionality and allows you to send a mention to another Brandwatch user to check.

null, or the email address (string) of a User with access to the given Project

author

Author is the nick name, user name or full name of the person who posted a mention. The name depends on the site on which it has been found.

"", or the author (string) of the mention

authorCity

Author City is the city with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the city (string) of the author

authorCityCode

Author City Code is the shortcode for the city with which a tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the city code (string) of the author (e.g. "bos1")

authorContinent

Author Continent Code is the continent with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the continent (string) of the author

authorContinentCode

Author Continent Code is the shortcode for the continent with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the continent code (string) of the author (e.g. "n-a")

authorCountry

Author Country is the country with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the country (string) of the author

authorCountryCode

Author Country Code is the shortcode for the country with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the country code (string) of the author (e.g. "us")

authorCounty

Author County is the county with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the county (string) of the author

authorCountyCode

Author County Code is the shortcode for the county with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the county code (string) of the author (e.g. "suf1")

authorLocation

Author Location is the location with which the tweet's author is associated. This is displayed in shortcode, in the following format: continent, country, state, county, city. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or a joined representation of the location codes (string) of the author (e.g. "n-a,us,mas3,suf1,bos1")

authorState

Author State is the state with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the state (string) of the author

authorStateCode

Author State Code is the shortcode for the state with which the tweet's author is associated. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or the state code (string) of the author (e.g. "mas3")

avatarUrl

Avatar Url is the url of the author's Twitter avatar. This is only available for mentions originating from Facebook, Instagram or Twitter.

null, or the url (string) of the author's avatar

averageDurationOfVisit

Average Duration of Visit is a metric pertaining to the traffic for the site that the mention originated from. It is the average number of minutes spent on the website by visitors.

0, or a positive integer

averageVisits

Average Visits is a metric pertaining to the traffic for the site that the mention originated from. It is calculated by taking the total number of visits to the site and dividing it by the total number of visitors to the site.

0, or a positive integer

backlinks

Backlinks is the number of pages across the web that link to this website. This is a metric provided by an external data provider, Moz.

0, or a positive integer

blogComments

Blog Comments is the number of comments a blog has. This metric is specific to mentions from a blog page type, and will be 0 for mentions originating from any other source.

0, or a positive integer

categories

Categories is a list of IDs of any categories that are applied to the mention.

Empty list, or a list of category IDs (int)

categoryDetails

Category Details is a list of details (ID of the category, name of the category, ID of the parent category, name of the parent category) for each of the categories that is applied to the mention.

Empty list, or a list dictionaries with details about each Category. These dictionaries would each be in the format: {id: int, name: string, parentId: int, parentName: string}

checked

Checked is part of the Brandwatch workflow functionality and can be used to indicate that a mention has been reviewed.

TRUE, FALSE

city

City is the name of the city from which the mention originated.

null, or the city name (string)

cityCode

City Code is the shortcode for the city from which the mention originated.

null, or the city code (string) (e.g. "bos1")

continent

Continent is the name of the continent from which the mention originated.

null, or the continent name (string)

continentCode

Continent Code is the shortcode for the continent from which the mention originated.

null, or the continent code (string) (e.g. "n-a")

country

Country is the name of the country from which the mention originated.

null, or the country name (string)

countryCode

Country Code is the shortcode for the country from which the mention originated.

null, or the country code (string) (e.g. "us")

county

County is the name of the county from which the mention originated.

null, or the county name (string)

countyCode

County Code is the shortcode for the county from which the mention originated.

null, or the county code (string) (e.g. "suf1")

date

Date is the date when the mention was posted.

"YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx"

displayUrls

Display Urls are the shortened links that appear in a mention. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, empty list, or a list of the shortened urls (string)

domain

Domain is the domain name of the website from which the mention originated.

domain (string) that the mention originated from

engagement

Deprecated

null

expandedUrls

Display Urls are the full urls for any shortened links that appear in a mention. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, empty list, or a list of the expanded urls (string)

facebookAuthorId

Facebook Author Id is the unique id of the Facebook author. This is a Facebook specific metric, and will be null for mentions not originating from Facebook.

null, or the author id (string)

facebookComments

Facebook Comments is number of comments on a Facebook mention. This is a Facebook specific metric, and will be 0 for mentions not originating from Facebook.

0, or a positive integer

facebookLikes

Facebook Likes is number of comments on a Facebook mention. This is a Facebook specific metric, and will be 0 for mentions not originating from Facebook.

0, or a positive integer

facebookRole

Facebook Role is the role of the Facebook user who authored the post ('owner' or 'audience'). A Facebook role of 'owner' would indicate that the author is posting on their own page, whereas a Facebook role of 'audience' would indicate that an author is posting on someone else's Facebook page. This is a Facebook specific metric, and will be null for mentions not originating from Facebook.

null, "owner", "audience"

facebookShares

Facebook Shares is number of times that a Facebook mention has been shared. This is a Facebook specific metric, and will be 0 for mentions not originating from Facebook.

0, or a positive integer

facebookSubtype

Facebook Subtype is the type of media shared in a Facebook mention ('link', 'photo' or 'video'). This is equivalent to the Facebook Media Type shown in the front end of the Brandwatch Analytics platform. This is a Facebook specific metric, and will be null for mentions not originating from Facebook.

null, "link", "photo", "status", "video"

forumPosts

Forum Posts is the number of messages in the forum thread, at the time the mention was found. This metric is specific to mentions from a forum page type, and will be 0 for mentions originating from any other source.

0, or a positive integer

forumViews

Form Views is the number of times the forum thread has been viewed by people, at the time the mention was found. This metric is specific to mentions from a forum page type, and will be 0 for mentions originating from any other source.

0, or a positive integer

fullname

Full Name is the full name of the author who posted the mention.

null, or author's full name (string)

gender

Gender is the gender ('male', 'female', 'unkown') of an author. This is a Twitter specific metric, and will be 'unknown' for mentions not originating from Twitter.

"male", "female", "unknown"

id

Id is a unique identifier given to each mention by Brandwatch.

int

impact

Impact is a Brandwatch metric to measure the potential impact of an author, site or mention. It's a logarithmic scale between 0-100 normalised for your data to help you find what's most interesting. The impact score takes into account how much potential a mention has to be seen, as well as how many times a mention has been viewed, shared or retweeted.

An integer from 0-100

importanceAmplification

Internally used to calculate the Impact Score

0, or a positive integer

importanceReach

Internally used to calculate the Reach Score

0, or a positive integer

impressions

Impressions is the potential number of viewers of a tweet. This is calculated by taking the sum of the followers of the account that originally posted a tweet, and the followers of any accounts that retweeted it. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

influence

Influence is the Kred Influence score of the author of this mention, at the time the mention was found (1-1000). This is a metric provided by an external data provider, Kred. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0-1000 (int)

insightsHashtag

Insights Hashtags is a list of hashtags identified within the mention. This is a Twitter and Instagram specific metric, and will be empty for mentions not originating from Twitter.

Empty list, or list of strings

insightsMentioned

Insights Mentioned is a list of Twitter handles identified within the mention. This is a Twitter and Instagram specific metric, and will be empty for mentions not originating from Twitter.

Empty list, or list of strings

instagramCommentCount

Instagram Comment Count is the number of comments on an Instagram mention. This is an Instagram specific metric, and will be 0 for mentions not originating from Instagram.

0, or a positive integer

instagramFollowerCount

Instagram Followers Count is the number of followers of the Instagram mention's author. This is an Instagram specific metric, and will be 0 for mentions not originating from Instagram.

0, or a positive integer

instagramFollowingCount

Instagram Following Count is the number of users that the author of an Instagram mention is following. This is an Instagram specific metric, and will be 0 for mentions not originating from Instagram.

0, or a positive integer

instagramLikeCount

Instagram Like Count is the number of likes on an Instagram mention. This is an Instagram specific metric, and will be 0 for mentions not originating from Instagram.

0, or a positive integer

instagramPostCount

Instagram Post Count is the number of posts on an Instagram mention. This is an Instagram specific metric, and will be 0 for mentions not originating from Instagram.

0, or a positive integer

interest

Interest is a list of the interests that are mentioned in the Twitter bio of the individual (not organization) that authored the mention. This is a Twitter specific metric, and will be an empty list for mentions not originating from Twitter.

Empty list, or a list of interests. All possible interests are: "Animals & Pets", "Fine arts", "Automotive", "Beauty/Health & Fitness", "Books", "Business", "Environment", "Family & Parenting", "Fashion", "Movies", "Food & Drinks", "Games", "Music", "Photo & Video", "Politics", "Science", "Shopping", "Sports", "Technology", "Travel", "TV"

language

Language is the shortcode for the language in which the mention was written.

Shortcode for the language (string) (e.g."en")

lastAssignmentDate

Last Assignment Date is part of the Brandwatch workflow functionality and shows the date when the mention was last assigned to a Brandwatch user. If the mention has never been assigned to a user, this field will be null.

null, or "YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx"

latitude

Latitude of a geo-tagged Tweet. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter as well as mentions that have not been goe-tagged.

float

locationName

Deprecated

null

longitude

Longitude of a geo-tagged Tweet. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter as well as mentions that have not been goe-tagged.

float

matchPositions

Match Positions is a list of details about words from the mention that matched the query string.

List of dictionaries in the following format: {length: int, start: int, text: string}

mediaUrls

Media Urls is a list of the urls associated with any media (e.g. photo, video) attached to the mention. This is a Twitter and Instagram specific metric, and will be null for mentions not originating from Twitter or Instagram.

Empty list, or a list of urls (string)

monthlyVisitors

Monthly Visitors is a metric pertaining to the traffic for the site that the mention originated from. It is the total number of unique visitors who have been to the website that month.

0, or a positive integer

mozRank

mozRank measures site credibility, similar to Google's PageRank. It's on a scale of 1-10, where 10 is most credible. This is a metric provided by an external data provider, moz.

0 - 10 (float)

noteIds

Note Ids is part of the Brandwatch workflow functionality and shows a list of the ids of any notes that have been added to the mention.

Empty list, or a list of note IDs (int)

outreach

Outreach is the Kred Outreach score of the author of this mention, at the time the mention was found (1-12). This is a metric provided by an external data provider, Kred. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0 - 12 (int)

pageType

Page Type describes the kind of website the mention was found on, e.g. a blog or forum.

All possible page types are: "blog", "facebook", "forum", "general", "image", "instagram", "news", "review", "twitter", "video"

pagesPerVisit

Pages Per Visit is a metric pertaining to the traffic for the site that the mention originated from. It is the average number of pages viewed by people visiting the website. This is equivalent to the Avg. Pages metric shown in the front end of the Brandwatch Analytics platform.

0, or a positive integer

percentFemaleVisitors

Percent Female Visitors is a metric pertaining to the traffic for the site that the mention originated from. It is the percentage of that site's visitors that are female.

0 - 100 (int)

percentMaleVisitors

Percent Male Visitors is a metric pertaining to the traffic for the site that the mention originated from. It is the percentage of that site's visitors that are male.

0 - 100 (int)

priority

Priority is part of the Brandwatch workflow functionality and can be used to indicate the priority of a mention (e.g. 'high', 'medium', 'low'). If the mention has never been marked with a priority, this field will be null.

null, "n/a", "low", "medium", "high"

professions

Profession is a list of the professions that are mentioned in the Twitter bio of the individual (not organization) that authored the mention. This is a Twitter specific metric, and will be an empty list for mentions not originating from Twitter.

Empty list, or a list of professions. All possible professions are: "Artist", "Executive", "Health practitioner", "Journalist", "Legal", "Politician", "Sales/Marketing/PR", "Scientist & Researcher", "Software developer & IT", "Sportpersons & Trainer", "Student", "Teacher & Lecturer"

queryId

Query Id is the unique identifier for the query that the mention originated from in Brandwatch.

int

queryName

Query Name is the name of the query that the mention originated from in Brandwatch.

string

reach

Reach is the sum of the Influence of the author and all of the authors who have retweeted. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

replyTo

Reply To is the url of the original tweet that this tweet is in reply to. This is a Twitter specific metric, and will be null for mentions not originating from Twitter and for tweets that are not a reply to any earlier tweet.

null, or the url (string) of the original tweet

resourceId

Resource Id is the unique identifier assigned to a mention when it is indexed in our database. This is for reference when using the Brandwatch API.

int

resourceType

Deprecated

null

retweetOf

Retweet Of is the url of the original tweet that this tweet is a retweet of. This is a Twitter specific metric, and will be null for mentions not originating from Twitter and for tweets that are not a retweet of any earlier tweet.

null, or the url (string) of the original tweet

sentiment

Sentiment is the tone of the mention: positive, negative or neutral.

"positive", "negative", "neutral"

shortUrls

Short Urls are the shortened links that appear in a mention. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, empty list, or a list of the shortened urls (string)

snippet

Snippet is a snippet of the mention text that best matches the query.

string

starred

Starred is part of the Brandwatch workflow functionality and can be used to indicate that a mention is interesting, or to mark it for any other purpose you choose.

TRUE, FALSE

state

State is the name of the state from which the mention originated.

null, or the state name (string)

stateCode

State Code is the shortcode for the state from which the mention originated.

null, or the state code (string) (e.g. "mas3")

status

Status is part of the Brandwatch workflow functionality and can be used to indicate the status of a mention (e.g. 'open', 'pending', 'closed'). If the mention has never been marked with a status, this field will be null.

null, "open", "pending", "closed"

subtype

Subtype is the same as the Media Type in the UI, and indicates the type of media included within a Facebook, Twitter, or Instagram mention.

null, "photo", "video", "other", "question", "link", "status"

tags

Tags is a list of the names of any tags that are applied to the mention.

Empty list, or a list of tag names (string)

threadAuthor

Thread Author is the name of the author of the original mention in the thread.

null, or the author name (string)

threadCreated

Thread Created is the date when the original mention in the thread was posted.

null, or "YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx"

threadEntryType

Thread Entry Type is the type of mention (post, reply, share) for mentions in a thread.

null, "reply", "post", "share"

threadId

Thread Id is the unique identifier of the thread, (as provided by Twitter or Facebook.?)

"0", or a the thread id (string)

threadURL

Thread Url is the url of the full thread which this mention appears in.

null, or the url (string) of the thread

title

Title is the title of the mention, as determined by Brandwatch.

string

trackedLinkClicks

Deprecated

null

trackedLinks

Deprecated

null

twitterAuthorId

Twitter Author Id is the unique id of the Twitter author. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, or a string

twitterFollowers

Twitter Followers is the number of followers of the Twitter mention's author. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

twitterFollowing

Twitter Following is the number of users that the author of a Twitter mention is following. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

twitterPostCount

Twitter Post Count is the total number of tweets that the author of the mention has posted. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

twitterReplyCount

Twitter Reply Count is the total number of replies to a tweet. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

twitterRetweets

Twitter Retweet Count is the total number of times that a tweet has been retweeted. This is a Twitter specific metric, and will be 0 for mentions not originating from Twitter.

0, or a positive integer

twitterRole

Twitter Role is the role of the Twitter user who authored the post ('owner' or 'audience'). A Twitter role of 'owner' would indicate that the author is posting on their own channel, whereas a Twitter role of 'audience' would indicate that an author is posting on someone else's channel. This is a Twitter specific metric, and will be null for mentions not originating from Twitter.

null, "owner", "audience"

twitterVerified

Twitter Verified indicates if the author of the mention is verified on Twitter (These are large accounts, usually celebrities). This is a Twitter specific metric, and will be false for all mentions not originating from Twitter.

TRUE, FALSE

url

Url is the url of the mention

string

wordCount

Deprecated

null

Retrieving Mentions

Listing the Mentions within your Query.