Getting Started¶

First, make sure you have:

Mention-Python installed
your Access token

See the Installation page for help if needed.

App¶

Assume your access token is stored in access_token for all API calls:

App Data¶

Retrieves useful details about the application.

Like some other resources, certain properties are translated given the Accept-Language header.

Example:

>>> from mention import AppDataAPI
>>> appData = AppDataAPI(access_token)

Alert¶

Create an Alert¶

You can create a new alert for a given account_id.

The minimum requirements for a new alert are the parameters name as a string, queryd as a dictionary and languages as a list of strings.

Example:

>>> name = "Nandos"
>>> queryd = {"type": "basic", "included_keywords":
... ["Nandos", "Flame-grilled Chicken", "Peri-Peri Sauce"]}
>>> languages = ["en"]
>>> newAlert = mention.CreateAnAlertAPI(access_token, account_id, name,
... queryd, languages)
>>> data = newAlert.query()

If the request was successful, the response will return the full alert data, like if you did a Fetch An Alert.

Please view the Create an alert page to see all the available parameters and CreateAnAlertAPI for formatting.

Fetch an Alert¶

Retrieve details about a single alert_id for a given account_id.

Example:

>>> nandosAlert = mention.FetchAnAlertAPI(access_token, account_id,
... alert_id)
>>> data = nandosAlert.query()
>>> data['alert']['name']
'Nandos'

>>> data['alert']['query']['included_keywords']
['Nandos', 'Flame-grilled Chicken', 'Peri-Peri Sauce']

Fetch all alerts of an account¶

Fetch a list of all alerts for a given account_id.

Example:

>>> allAlerts = mention.FetchAlertsAPI(access_token, account_id)
>>> data = nandosAlert.query()
>>> alertsList = data['alerts']
>>> alertsList[5]['alert']['name']
'Nandos'

>>> data['alert']['query']['included_keywords']
['Nandos', 'Flame-grilled Chicken', 'Peri-Peri Sauce']

Update an Alert¶

Modifies an existing alert, usually to update the criteria and to improve the search’s efficiency for a given account_id.

This API call has all of the same parameters as Create An Alert.

Example:

>>> name = "Nandos"
>>> queryd = {"type": "basic", "included_keywords":
...         ["Nandos", "Flame-grilled Chicken", "Peri-Peri Sauce",
...         "Garlic Rolls"]}
>>> languages = ["en", "af"]
>>> countries = ["US", "ZA", "UK"]
>>> sources = ["web", "twitter"]

>>> updateNandosAlert = mention.UpdateAnAlertAPI(access_token, account_id,
... name, queryd, languages, countries, sources)

>>> data = updateNandosAlert.query()

Again a successful request will return the full alert data as a response.

Please view the Update an alert page to see all the available parameters and UpdateAnAlertAPI for formatting.

Mention¶

Fetch a mention¶

Retrieve details about a single mention_id for a given alert_id from an account_id.

Example:

>>> nandosMention = mention.FetchAMentionAPI(access_token, account_id,
... alert_id, mention_id)
>>> data = nandosMention.query()
>>> data['title']
"Nando's launches their own food ordering app"

>>> data['description']
"Nando's has launched their own app that will allow people to order their favourite meal from the comfort of their own home."

>>> data['original_url']
"https:\/\/www.iol.co.za\/business-report\/technology\/nandos-launches-their-own-food-ordering-app-18378360"

Fetch mentions¶

Fetch a list of all mention for a given alert_id from an account_id.

There are 16 parameters which can be used to filter the mentions you receive as a response. Please note that some parameters cannot be used in combination with others. For example since_id cannot be combined with before_date, not_before_date or cursor.

Please view the Fetch Mentions page to see all the available parameters and FetchAllMentionsAPI for formatting. For example read and favourite uses the python boolean type instead of a string.

Example:

>>> nandosMentions = mention.FetchAllMentionsAPI(access_token, account_id,
... alert_id, limit="1000",
... before_date="2018-11-25 12:00",
... not_before_date="2018-10-04 12:00",
... source="twitter",
... read=True)

>>> data = nandosMentions.query()
>>> firstMention = data['mentions'][0]
>>> firstMention['title']
"Nando's launches their own food ordering app"

>>> firstMention['description']
"Nando's has launched their own app that will allow people to order their favourite meal from the comfort of their own home."

>>> firstMention['original_url']
"https:\/\/www.iol.co.za\/business-report\/technology\/nandos-launches-their-own-food-ordering-app-18378360"

>>> if len(data['_links']['more']['href']) == 0:
>>>         print('No more mentions to receive.')
"No more mentions to receive."

Note

limit is capped at 1000. To view more mentions use the _links, more and pull urls to receive all of your mentions. To learn more about this, read the bottom of Fetch Mentions.

Curate a mention¶

Updates an existing mention_id for a given alert_id from an account_id. These update concern majorly classification of the mention: indicating the folder, tags, effective tone of the mention, etc… You cannot modify the content of a mention, or its source.

There are 6 parameters which can be used to change how a mention is classified. favorite and trashed can only be editted by an admin. Please view the Curate Mention page to see all the available parameters and CurateAMentionAPI for formatting.

Example:

>>> nandosMention = mention.CurateAMentionAPI(access_token, account_id,
... alert_id,
... mention_id,
... favorite=True,
... tone='-1')

>>> data = nandosMention.query()
>>> data['favorite']
'true'

Note

A mention can only be associated with an existing tag. This means that you have to create a tag first. Mention-Python does not currently support this feature.

Mark all mentions read¶

Mark all mentions as read for a given alert_id from an account_id.

Example:

>>> nandos = mention.MarkAllMentionsReadAPI(access_token, account_id,
... alert_id)

>>> data = nandos.query()