All Collections
API service
Mentionlytics API Parameters & Fields
Mentionlytics API Parameters & Fields

A detailed list about every parameter and field you can extract from Mentionlytics' API service

Manos avatar
Written by Manos
Updated over a week ago

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:
web | twitter | facebook | youtube | instagram | linkedin | reddit | tiktok

link

link to the profile

verified

true/false if the profile is verified

rank

The rank of website for a web page
(only for web mentioners - sites)

global_rank

The global rank of website for a web page
(only for web mentioners - sites)

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
false (default) returns any word, not only hashtags.

adjacentWords

1 for single words (default),
2 for two adjacent word phrases and
3 for three adjacent word phrases or use
0 for mix of the above

ignoreMainKeyword

true (default) ignores the main keyword of the mentions tracker that gathered the mentions
false includes the tracker main keyword in the top keywords list.

Explanation of JSON fields

Name

Description

keyword

string
the word, hashtag or word phrase

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

Did this answer your question?