Currently, the following endpoints are available in the Mentionlytics API:
/api/mentions: To retrieve your detailed mention data with each mention as a separate object
/api/aggregation : To retrieve aggregated data of your mentions (e.g. total number of mentions, likes, shares and other metrics )
/api/mentioners : To retrieve the social profiles and pages that have mentioned your keywords.
/api/top-keywords : To retrieve the words, hashtags or phrases that occure more often in your mentions.
/api/demographics/owned-media : To retrieve number of mentions based on gender and age demographics.
/api/top-countries : To retrieve statistics on mentions, engagement, and reach categorized by country.
/api/top-languages : To retrieve statistics on mentions, engagement, and reach categorized by language.
To use the endpoints, first, you need to get your token .
Endpoint: /api/mentions
You can use the mention API URL to get results as bellow:
https://
app.mentionlytics.com/api/mentions?token=xxxxxxxxx
The above request will return a JSON list of the mentions in your Brand Monitoring mention tracker for the past 7 days. This is the default functionality but you can use more parameters as described below to customize your results.
URL Parameters
The following list of parameters can also be added to your request URL in addition to the token to get the results you want.
URL Parameters | Type | Description |
&startDate | YYYYMMDD | The first date of the period to retrieve mentions |
&endDate | YYYYMMDD | The last date of the period to retrieve mentions |
&sentiment | negative | positive | neutral | Filters the mentions to negative or positive or neutral as requested |
&page_no | X | By default the page size of the retrieved mentions is 20, so you need to move through the next pages to get the rest of your mentions. Starting from 0 as the first page. |
&per_page | X | Changes the size of the page from the default value of 20 to the indicated value. The maximum page is 10,000 mentions but is recommended to keep it lower as the performance might be very poor for large values. Use page_no instead to get all your results. |
&channels | %5B1,2,3,4,5,7,99%5D | Filters the mention source channel by the channel ID: 1 - Web 2 - Twitter 3 - Facebook 4 - Youtube 5 - Instagram 7 - Reviews 99 - Others (Linkedin, Reddit). Remove Channel numbers that you don't need from the query parameter. If you leave it blank it returns mentions from all channels. |
&commtracks | all | brandmonitoring | competitors | leads | Choose which Mention Trackers' mentions to retrieve by indicating their category or use all to get all mentions from all trackers. |
&country | e.g. GB, GR, EG, US, CO, HK etc. | Filters the Mentions by country. Use a standard 2 digit country code. |
&language | e.g. en, el, de, ar etc. | Filters the Mentions by language. Use a standard 2 digit language code. |
&ordering | date | rank | engagement | The default ordering of results is by date. You can set to rank which means ordering the web mentions with top-ranking sites first while social mentions are ranked by profiles with more followers first (where followers data is available). Ordering by engagement will sort the results by the ones with more engagement (likes+comments+shares) first. |
Example of a more complex query:
https://app.mentionlytics.com/api/mentions?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en
https://app.mentionlytics.com/api/mentions?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en
Explanation of JSON fields
Type | Description |
id | identity of mentions |
uid | profile id |
uu_id | universally unique identifier |
mchannel | channel's name |
mchannel_id | channel(source) id (1=Web, 2=Twitter, 3=Facebook, 4=YouTube, 5=Instagram, 99=others (LinkedIn, Reddit etc) 7=Reviews (Google Play-type_name=1, TripAdvisor-type_name=0 |
sentiment_text | sentiment result (positive/negative/neutral) pub_date = date of publication |
manual_sentiment | if the user changed sentiment value manually (true/false) |
pub_datetime | date of publication + time |
relevance | the relevance of a result (0.25-1) |
mEngagement | number of likes/shares etc |
ftext | mention's text |
profile_name | name of profile/site left mention |
screen_name | username of profile/site left mention |
profile_username | username of profile/site left mention |
profile_image | URL of profile image - social |
profile_image_url | URL of profile image - social |
profile_uu_id | profile unique identity |
followers_count | number of followers a profile has |
profile_meta | data about the profile for example location (if available) |
meta_count1 | country rank for Web results/followers for social |
post_count | number of posts the profile has made |
profile_description | description of profile |
profile_type_name | text that specifies a profile's type (user/page, etc) |
statuses_count | number of tweets the profile has made (same as post_count) |
name | profile's name |
mRank | Alexa ranking (for web results) |
campaign | name of the tracker |
commtrack | the keyword |
commtrack_id | keyword's id |
total_count | mentions total for the specific day |
type_name | text that specifies mention's type |
plus_shares | Google Plus share count |
pin_shares | Pinterest share count |
body | Web page text (applied for web results only) |
body_html | Web page HTML (applied for web results only) |
campaign_id | tracker's identity |
cmeta_retweets | retweet count (for a web result) |
cf1i | retweet count (for Twitter results only) |
msearch_id | search id (when each new channel search begins a unique id is assigned) |
profile_id | profile id in Mentionlytics' database |
thumb_url | mention's image URL |
totals_pub_date | a specific day between the start date and end date |
totals_total_count | total results for the specific day |
followers_at_post | number of followers a profile has when a post is recorded |
Endpoint: /api/aggregation
The aggregation endpoint will retrieve totals of mentions, shares, likes, sentiment etc. for all the mentions of a specific period.
Sample use:
https://
app.mentionlytics.com/api/aggregation?token=xxxxxxxxx
Details:
The above request will return a JSON list of the aggregated statistics (like reach, engagement, sentiment etc) in your Brand Monitoring mention tracker for the past 7 days. This is the default functionality but you can use more parameters to customize your results. The URL parameters are the same as the /api/mentions endpoint, so you can see detailed description above (first table in this document) .
Example of a more Complex query:
https://app.mentionlytics.com/api/aggregation?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en
https://app.mentionlytics.com/api/aggregation?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en
Explanation of JSON fields
Type | Description |
mentions - object of {web,social,total} | total: total mentions, web: object of {sites,total}, social: object of {total,users} |
reach - object of {web, twitter, facebook, youtube, instagram, reviews, others, total} | For every post/mention we add the number of followers of the profile that performed it, grouped by channel id and summarized as total |
unique_reach - object of {web, twitter, facebook, youtube, instagram, reviews, others, total} | For every post/mention we add the number of followers of the UNIQUE profile that performed it, grouped by channel id and summarized as total |
sentiment - object of {positive, negative, neutral} | positive: contains the total of positive mentions per channel and also sum of all positive totals to field total. negative & neutral: same with positive |
engagement - object of {total, likes, comments, shares, views, reviews_average, web_shares_on_social, instragram_stories} | likes: sum of likes and thumbs ups comments: sum of comments shares: sum of shares and retweets views: Sum of Youtube, Tiktok and Instagram Stories views reviews_average: the average score of reviews between 1 and 5 (if available) web_shares_on_social: Shares on social media of Web pages and Youtube videos instagram_stories - object of {impression: the total number of times your story was viewed, taps_forward: Number of times someone tapped to the next story, taps_back: The amount of times someone tapped back to see the previous story}
|
Endpoint: /api/mentioners
The mentioners endpoint will retrieve the social profiles and pages that have mentioned your keywords.
Sample use:
https://
app.mentionlytics.com/api/mentioners?token=xxxxxxxxx
Details:
The above request will return a JSON list of the top mentioners (ordered by reach, engagement or number of mentions) from your Brand Monitoring mention tracker, for the past 7 days. This is the default functionality, but you can use more parameters to customize your results. The URL parameters are the same as the /api/mentions endpoint, so you can see the detailed description above (first table in this document) .
Example of a more Complex query:
https://app.mentionlytics.com/api/mentioners?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en&ordering=reach&sortDesc=true
https://app.mentionlytics.com/api/mentioners?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en&ordering=reach&sortDesc=true
Additional Parameters
Type | Description |
ordering | can be ‘mentions’ or ‘engagement’ or ‘reach’ (default is ‘reach’) |
sortDesc | true/false (default is true) |
per_page | default:25 mentioners per page max value is 500 |
Explanation of JSON fields
Type | Description |
id | Mentionlytics profile id |
uu_id | universally unique identifier |
name | profile name or title (if the profile is from Youtube) |
screen_name | profile screen name |
description | profile description
|
country | Country code of profile (if available) |
lang_detected | profile language code |
channel | The channel of the profile can be one of the following: |
link | link to the profile |
verified | true/false if the profile is verified |
rank | The rank of website for a web page |
global_rank | The global rank of website for a web page |
engagement_sum | total engagement |
follow_count | total following for the profile |
followers_count | total followers or subscribers (if profile is YouTube) |
post_count | total post or videos (if profile is Youtube) |
view_count | total viewers (only for YouTube profiles) |
mentions_count | total mentions in Mentionlytics |
neg_count | total negative mentions |
pos_count | total positive mentions |
neu_count | total neutral mentions |
Endpoint: /api/top-keywords
The top-keywords endpoint will retrieve the most often encountered words or hashtags in your mentions.
Sample use:
https://
app.mentionlytics.com/api/top-keywords?token=xxxxxxxxx
Details:
The above request will return a JSON list of the top keywords (ordered by reach/rank, engagement or number of mentions) from your Brand Monitoring mention tracker, for the past 7 days. This is the default functionality, but you can use more parameters to customize your results. The URL parameters are the same as the /api/mentions endpoint, so you can see the detailed description above (first table in this document) .
Example of a more Complex query:
https://app.mentionlytics.com/api/top-keywords?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en&ordering=reach
https://app.mentionlytics.com/api/top-keywords?token=xxxxxxxxx&startDate=20190129&endDate=20190227&channels=%5B2%5D&commtracks=%2231016$31021$31017$31018$31019$31020$31022$31023$31024$31025$31027%22&sentiment=negative&country=US&language=en&ordering=reach
Additional Parameters
Name | Description |
ordering | can be ‘mentions’ or ‘engagement’ or ‘reach’ (default is ‘mentions’) |
resultsLimit | Number (limit how many top keywords will be fetched) [default:100] |
onlyHashtags | true for returning only #hashtags, not just any word |
adjacentWords | 1 for single words (default), |
ignoreMainKeyword | true (default) ignores the main keyword of the mentions tracker that gathered the mentions |
Explanation of JSON fields
Name | Description |
keyword | string |
weight | number total_mentions or total_engagement or total reach (depending on the ordering parameter) |
total_mentions | number how many mentions have this keyword |
total_engagement | number Total engagement of all the mentions with the keyword |
total_reach | number Total reach of all the mentions with the keyword |
total_positive | number Total number of mentions that have the keyword and have positive sentiment |
total_negative | Total number of mentions that have the keyword and have negative sentiment |
top_country_code | string country with most mentions to this keyword in ISO country format eg. US, GB, GR) |
top_sentiment | neutral/negative/positive what is the dominant sentiment of the mentions |
adjacentWords | 1/2/3 how many adjacent words are in this keyword (useful when 0 is selected in parameters for mixed) |
Endpoint: /api/demographics/owned-media
The owned-media demographics endpoint provides insights into the total number of mentions based on gender and age demographics.
Sample use:
Details:
This endpoint returns a JSON object containing aggregated statistics on mentions categorized by gender and age groups. By default, it provides data for the past 7 days. Users can customize the results using optional parameters. The parameters align with those used in the /api/mentions endpoint.
Example of a more Complex query:
https://app.mentionlytics.com/api/demographics/owned-media?startDate=2023-12-14&endDate=2023-09-14&token=xxxxxxxxx&filterAgeByGender=male
https://app.mentionlytics.com /api/demographics/owned-media?startDate=2023-12-14&endDate=2023-09-14&token= xxxxxxxxx&filterAgeByGender=male
Additional Parameters:
Name | Description |
filterGenderByAge | Used to filter gender demographics by age (default null). Can be: 13-17 | 18-24 | 25-34 | 35-44 | 45-54 | 55-65 | 65+ |
filterAgeByGender | Used to filter age demographics by gender (default null). Can be: male | female | unspecified |
Explanation of JSON fields:
Name | Description |
genders | Object of { male, female, unspecified }. Contains number of mentions grouped by Gender |
ages | Object of { 13-17, 18-24, 25-34, 35-44, 45-54, 55-65, 65+ }. Contains number of mentions grouped by age groups |
Endpoint: /api/top-countries
The top-countries endpoint retrieves statistics on mentions, engagement, and reach categorized by country.
Sample use:
Details:
The above request will return a JSON list of the aggregated statistics (like reach, engagement, sentiment etc) grouped by country. This is the default functionality but you can use more parameters to customize your results. The URL parameters are the same as the /api/mentions endpoint, so you can see detailed description above (first table in this document).
Example of a more Complex query:
https://app.mentionlytics.com/api/top-countries?token=xxxxxxxxx&ordering=reach&sortDesc=false
https://app.mentionlytics.com/api/top-countries?token=xxxxxxxxx&ordering=reach&sortDesc=false
Additional Parameters:
Name | Description |
ordering | Used to order countries by mentions | engagement | reach. Default: mentions. |
sortDesc | Default: true. Can be true or false. |
usRestriction | Default: false. Can be true or false. |
Explanation of JSON fields:
Name | Description |
country_code | 2-letter ISO-3166. Like US, GB, GR.. |
total_mentions | (Number) Total mentions. |
total_engagement | (Number) Total engagement. |
total_reach | (Number) Total reach. |
total_positive | (Number) Total positive mentions |
total_negative | (Number) Total negative mentions |
Endpoint: /api/top-languages
The top-languages endpoint retrieves statistics on mentions, engagement, and reach categorized by language.
Sample use:
Details:
The above request will return a JSON list of the aggregated statistics (like reach, engagement, etc) grouped by language. This is the default functionality but you can use more parameters to customize your results. The URL parameters are the same as the /api/mentions endpoint, so you can see detailed description above (first table in this document).
Example of a more Complex query:
https://app.mentionlytics.com/api/top-languages?token=xxxxxxxxx&ordering=reach&sortDesc=false
https://app.mentionlytics.com/api/top-languages?token=xxxxxxxxx&ordering=reach&sortDesc=false
Additional Parameters:
Name | Description |
ordering | Used to order countries by mentions | engagement | reach. Default: mentions. |
sortDesc | Default: true. Can be true or false. |
usRestriction | Default: false. Can be true or false. |
Explanation of JSON fields:
Name | Description |
language_code | 2-letter like el, en. |
total_mentions | (Number) Total mentions. |
total_engagement | (Number) Total engagement. |
total_reach | (Number) Total reach. |
total_positive | (Number) Total positive mentions |
total_negative | (Number) Total negative mentions |