GET statistics

GET /accounts/{account_id}/stats

This method will allow you to fetch a general statistics from the API, alert by alert.

Parameters

  • account_id (string) - Id of the account

Minimal curl example

curl -ig 'https://api.mention.net/api/accounts/{account_id}/stats?from=2016-01-14T00%3A00%3A00.0&to=2016-01-20T23%3A59%3A59.0&timezone=Europe%2FBerlin&interval=P1D&favorite=false&alerts%5B%5D=28222&week_day_stats=true&week_day_by_hour_stats=true&tones_per_interval_stats=true&country_stats=true&influencers=true' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Accept-Version: 1.19'

Available properties

as query string attributes!

In stats, a range of interesting filters enable you to finetune your export.

Properties _ Definition Example
alerts[] required alerts for which stats must be fetched alerts[]=112233&alerts[]=1
from optional stats are to be fetched for mentions retrieved after that date 2015-03-27T00:00:00.0
to optional stats are fetched for mentions retrieved before that date 2016-01-10T00:00:00.0
timezone optional timezone of the from and to Europe/Berlin
interval optional Periodicity of statistics returned. it may be daily(P1D), weekly(P1W) or monthly(P1M). P1D
favorite optional Select only statistics from mentions in favorite folder. This can be added to important. true
important optional Select only statistics from mentions in important folder. This can be added to favorite. true
tones[] optional Select only statistics about mentions of certain tones. tones[]=-1&tones[]=0
languages[] optional Select only statistics from mentions in the specified Language, defined by its language code. languages[]=en
sources[] optional Select only statistics from mentions provided by specified sources. sources[]=twitter
countries[] optional Select only statistics about mentions of certain countries. countries[]=US
tags[] optional Select only statistics about mentions of certain tags. tags[]=space
week_day_stats optional Classify mentions by week day. This cannot coexist with week_day_by_hour_stats in the same query. true
week_day_by_hour_stats optional Classify mentions by hour of each week day. This cannot coexist with week_day_stats in the same query. false
country_stats optional Whether to return country statistics, and how much top countries to return. Takes an integer. Alterntively, true is equivalent to 10, and false to 0. Defaults to 0. 10
influencers optional Boolean value to be put to true id you wish to retrieve top ten web/twitter influencers for selected alerts. It will return al list of author ids for web and twitter sources, associated with their score. true
reach_per_interval_stats optional Boolean value that you can put to true if you want to return direct, cumulative, and domain reach false
author_influence.score optional Filter with author score min and max "20:60"

Alerts

alerts[]

This is a list of alert ids. This parameter is required. It indicates for which alerts you want to fetch statistics. this is a querystring array, so that you can fetch statistics for multiple alerts with a single query.

From

from

Datetime indicates that you want your statistics to be generated only for mentions fetched after the from date. Its format respects our date format standard.

To

to

Datetime that indicates that you want your statistics to be generated only for mentions fetched before the to date. Its format respects our date format standard.

Timezone

timezone

Timezone that indicates the timezone applicable on the from and to parameters.

Interval

interval

It indicates the periodicity of statistics returned. Currently 3 values possible:

  • P1D (daily)
  • P1W (weekly)
  • P1M (monthly)

Favorite

favorite

Boolean value that indicates that you want to select only favorited mentions as base of your statistics generation. it may be added to important.

Important

important

Boolean value that indicates that you want to select only important mentions as base of your statistics. It may be added to favorite.

Tones

tones[]

List of numerical values representing tones. It indicates that you want to select only mentions of that tones as base for your statistics generation. For the list of tones, you can fetch the app/data

Languages

languages[]

List of languages codes. It indicates that you want to select only mentions of these languages as base for your statistics generation. For the list of languages, you can fetch the app/data.

Sources

sources[]

List of source codes. It indicates that you want to select only mentions retrieved from these sources as base of your statistics. For the list of sources, you can fetch the app/data.

Countries

countries

List of countries codes. It indicates that you want to select only mentions retrieved from these countries as base of your statistics. For the list of countries, you can fetch the app/data.

Tags

tags

List of tags. It indicates that you want to select only mentions retrieved from these tags as base of your statistics.

Week day stats

week_day_stats

Boolean value that indicates your wish to classify mentions by week day.

it cannot coexist with week_day_by_hour_stats.

Week day by hour stats

week_day_by_hour_stats

Boolean value that indicates your wish to classify mentions by hour of each week day.

It cannot coexist with week_day_stats.

Country stats

country_stats

Boolean value that indicates your wish to classify mentions by countries.

Influencers

influencers

Boolean value that indicates your wish to retrieve top 10 influencers of each channels (web & twitter), for each given alert. It will return a list of influencer ids with their score. You can then get the full author characteristics by fetching these authors by id.

Reach per interval stats

reach_per_interval_stats

Boolean value that you can put to true if you want to return direct, cumulative, and domain reach.

Author Influence Score

author_influence.score

Allow to filter mentions between author scores min and max.
The field must be a string using the following format: "<min>:<max>" where <min> stands for the minimum value of author score to match (inclusive and optional) and <max> stands for the maximum value of author score to match (inclusive and optional).

Examples:

  • "0:100": matches mentions whose influence score is between 0 and 100
  • "50:": matches mentions whose influence score is >= 50
  • ":": no score filter applied
  • ":90": matches mentions whose influence score is <= 90

Request example

  • Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept-Version: 1.19

Response example

  • Body

Structure will be:

{
    "stats": {
        "28222": { ... alert_stats ... },
        "28223": { ... alert_stats ... },
        ...
    },
    "from": "2016-01-14T00:00:00.0+01:00",
    "to": "2016-01-20T23:59:59.0+01:00" 
}

Where keys 28222 and 28223 are alert ids, and values {... alert_stats ...} are statistics of each alert. from and to are the dates used to time frame the statistics.

Sometimes, statistics are not fully generated yet. In that case, the additional partial parameter is returned as true. This means that you should try again later.

{
    "stats": {
        "28222":{}
    },
    "from": "2016-01-14T00:00:00.0+01:00",
    "to": "2016-01-20T23:59:59.0+01:00",
    "partial": true
}

Alert stats

... alert_stats ...

The statistics of an alert always have the following structure:

{
    "week_days_total": {
        "data": {
            "1": [3, 36, 2, 4, 1, 1, 4, 6, 3, 20, 16, 15, 14, 24, 10, 17, 13, 8, 8, 7, 5, 7, 4, 12],
            "2": [5, 33, 3, 4, 2, 2, 4, 5, 7, 8, 5, 5, 15, 38, 8, 8, 32, 18, 17, 6, 7, 4, 7, 5],
            "3": [1, 11, 4, 2, 1, 0, 4, 2, 11, 40, 28, 6, 10, 10, 7, 6, 27, 6, 1, 2, 0, 0, 0, 0],
            "4": [1, 13, 2, 3, 4, 5, 19, 6, 13, 26, 15, 24, 15, 18, 47, 27, 33, 15, 11, 3, 9, 9, 2, 2],
            "5": [8, 24, 4, 1, 4, 2, 8, 6, 12, 23, 23, 34, 12, 6, 17, 13, 30, 5, 23, 4, 3, 3, 4, 3],
            "6": [2, 17, 2, 2, 3, 6, 9, 3, 14, 26, 2, 6, 6, 4, 3, 3, 4, 3, 2, 8, 6, 2, 7, 2],
            "7": [4, 5, 0, 1, 0, 1, 7, 4, 10, 8, 3, 2, 13, 12, 3, 8, 8, 12, 10, 2, 3, 3, 0, 12]
        },
        "total": 1534
    },
    "mentions_per_interval": {
        "avg": 219.14285714286,
        "data": {
            "2016-01-14": 322,
            "2016-01-15": 272,
            "2016-01-16": 142,
            "2016-01-17": 131,
            "2016-01-18": 240,
            "2016-01-19": 248,
            "2016-01-20": 179
        },
        "max": 322,
        "min": 131,
        "total": 1534
    },
    "tones_per_interval": {
        "data": {
            "2016-01-14": {
                "-1": 7,
                "0": 267,
                "1": 48
            },
            "2016-01-15": {
                "-1": 4,
                "0": 215,
                "1": 53
            },
            "2016-01-16": {
                "-1": 0,
                "0": 108,
                "1": 34
            },
            "2016-01-17": {
                "-1": 0,
                "0": 112,
                "1": 19
            },
            "2016-01-18": {
                "-1": 2,
                "0": 209,
                "1": 29
            },
            "2016-01-19": {
                "-1": 2,
                "0": 218,
                "1": 28
            },
            "2016-01-20": {
                "-1": 2,
                "0": 157,
                "1": 20
            }
        },
        "total": 1534
    },
    "direct_reach_per_interval": {
        "data": {
            "2016-01-14": {
                "sum": 507,
                "max": 267,
                "avg": 48.5
            },
            "2016-01-15": {
                "sum": 544,
                "max": 215,
                "avg": 53.1
            },
            "2016-01-16": {
                "sum": 390,
                "max": 108,
                "avg": 34
            },
            "2016-01-17": {
                "sum": 620,
                "max": 112,
                "avg": 19
            },
            "2016-01-18": {
                "sum": 530,
                "sum": 209,
                "avg": 29
            },
            "2016-01-19": {
                "sum": 982,
                "max": 218,
                "avg": 28
            },
            "2016-01-20": {
                "sum": 298,
                "max": 157,
                "avg": 20
            }
        }
    },
    "cumulative_reach_per_interval": {
        "data": {
            "2016-01-14": {
                "sum": 510,
                "max": 267,
                "avg": 48.8
            },
            "2016-01-15": {
                "sum": 545,
                "max": 215,
                "avg": 53.4
            },
            "2016-01-16": {
                "sum": 390,
                "max": 108,
                "avg": 34
            },
            "2016-01-17": {
                "sum": 621,
                "max": 112,
                "avg": 19.1
            },
            "2016-01-18": {
                "sum": 530,
                "sum": 209,
                "avg": 29
            },
            "2016-01-19": {
                "sum": 986,
                "max": 218,
                "avg": 29.7
            },
            "2016-01-20": {
                "sum": 300,
                "max": 157,
                "avg": 20.2
            }
        }
    },
    "domain_reach_per_interval": {
        "data": {
            "2016-01-14": {
                "sum": 0,
                "max": 0,
                "avg": 0
            },
            "2016-01-15": {
                "sum": 0,
                "max": 0,
                "avg": 0
            },
            "2016-01-16": {
                "sum": 0,
                "max": 0,
                "avg": 0
            },
            "2016-01-17": {
                "sum": 0,
                "max": 0,
                "avg": 0
            },
            "2016-01-18": {
                "sum": 0,
                "max": 0,
                "avg": 0
            },
            "2016-01-19": {
                "sum": 0,
                "max": 0,
                "avg": 0
            },
            "2016-01-20": {
                "sum": 0,
                "max": 0,
                "avg": 0
            }
        }
    },
    "influencers": {
        "data": {
            "twitter": {
                "420369523": {
                    "id": "420369523",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/OpenClassrooms",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/OpenClassrooms",
                    "name": "OpenClassrooms",
                    "score": 70,
                    "scored_id": "OpenClassrooms"
                },
                "31192139652": {
                    "id": "31192139652",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/AnnWalthour",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/AnnWalthour",
                    "name": "AnnWalthour",
                    "score": 62,
                    "scored_id": "AnnWalthour"
                },
                "82121083": {
                    "id": "82121083",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/Crell",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/Crell",
                    "name": "Crell",
                    "score": 61,
                    "scored_id": "Crell"
                },
                "688759903": {
                    "id": "688759903",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/GovsInfo",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/GovsInfo",
                    "name": "GovsInfo",
                    "score": 61,
                    "scored_id": "GovsInfo"
                },
                "4960453": {
                    "id": "4960453",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/symfony",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/symfony",
                    "name": "symfony",
                    "score": 61,
                    "scored_id": "symfony"
                },
                "1677083": {
                    "id": "1677083",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/itknowingness",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/itknowingness",
                    "name": "itknowingness",
                    "score": 60,
                    "scored_id": "itknowingness"
                },
                "4468073": {
                    "id": "4468073",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/webcoupdoeil",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/webcoupdoeil",
                    "name": "webcoupdoeil",
                    "score": 60,
                    "scored_id": "webcoupdoeil"
                },
                "31085769732": {
                    "id": "31085769732",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/AGlimpsofHeaven",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/AGlimpsofHeaven",
                    "name": "AGlimpsofHeaven",
                    "score": 60,
                    "scored_id": "AGlimpsofHeaven"
                },
                "481746643": {
                    "id": "481746643",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/atlantic2",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/atlantic2",
                    "name": "atlantic2",
                    "score": 59,
                    "scored_id": "atlantic2"
                },
                "530750533": {
                    "id": "530750533",
                    "alert_id": 28222,
                    "author_unique_id": "twitter:user\/livecodingtv",
                    "kind": "twitter",
                    "url": "https:\/\/twitter.com\/livecodingtv",
                    "name": "livecodingtv",
                    "score": 58,
                    "scored_id": "livecodingtv"
                }
            },
            "web": {
                "5274473475": {
                    "id": "5274473475",
                    "alert_id": 28222,
                    "author_unique_id": "github.com",
                    "kind": "web",
                    "url": "https:\/\/github.com",
                    "name": "github.com",
                    "score": 86,
                    "scored_id": "github.com"
                },
                "5274496515": {
                    "id": "5274496515",
                    "alert_id": 28222,
                    "author_unique_id": "reddit.com",
                    "kind": "web",
                    "url": "http:\/\/www.reddit.com",
                    "name": "reddit.com",
                    "score": 85,
                    "scored_id": "reddit.com"
                },
                "5274657795": {
                    "id": "5274657795",
                    "alert_id": 28222,
                    "author_unique_id": "slideshare.net",
                    "kind": "web",
                    "url": "http:\/\/slideshare.net",
                    "name": "slideshare.net",
                    "score": 70,
                    "scored_id": "slideshare.net"
                },
                "19616147716": {
                    "id": "19616147716",
                    "alert_id": 28222,
                    "author_unique_id": "wiki.phpbb.com",
                    "kind": "web",
                    "url": "https:\/\/phpbb.com",
                    "name": "wiki.phpbb.com",
                    "score": 66,
                    "scored_id": "wiki.phpbb.com"
                },
                "5274481155": {
                    "id": "5274481155",
                    "alert_id": 28222,
                    "author_unique_id": "symfony.com",
                    "kind": "web",
                    "url": "http:\/\/symfony.com",
                    "name": "symfony.com",
                    "score": 64,
                    "scored_id": "symfony.com"
                },
                "30500996996": {
                    "id": "30500996996",
                    "alert_id": 28222,
                    "author_unique_id": "docs.aws.amazon.com",
                    "kind": "web",
                    "url": "https:\/\/amazon.com",
                    "name": "docs.aws.amazon.com",
                    "score": 59,
                    "scored_id": "docs.aws.amazon.com"
                },
                "5274509827": {
                    "id": "5274509827",
                    "alert_id": 28222,
                    "author_unique_id": "news.ycombinator.com",
                    "kind": "web",
                    "url": "https:\/\/news.ycombinator.com",
                    "name": "news.ycombinator.com",
                    "score": 59,
                    "scored_id": "news.ycombinator.com"
                },
                "30405826308": {
                    "id": "30405826308",
                    "alert_id": 28222,
                    "author_unique_id": "nginx.com",
                    "kind": "web",
                    "url": "https:\/\/nginx.com",
                    "name": "nginx.com",
                    "score": 59,
                    "scored_id": "nginx.com"
                },
                "15873837828": {
                    "id": "15873837828",
                    "alert_id": 28222,
                    "author_unique_id": "fr.viadeo.com",
                    "kind": "web",
                    "url": "http:\/\/viadeo.com",
                    "name": "fr.viadeo.com",
                    "score": 57,
                    "scored_id": "fr.viadeo.com"
                },
                "5274573443": {
                    "id": "5274573443",
                    "alert_id": 28222,
                    "author_unique_id": "freelancer.com",
                    "kind": "web",
                    "url": "https:\/\/freelancer.com",
                    "name": "freelancer.com",
                    "score": 57,
                    "scored_id": "freelancer.com"
                }
            }
        },
        "total": 20,
        "ready": true
    },
    "countries_total": {
        "data": {
            "US": 458,
            "FR": 299,
            "GB": 232,
            "ES": 136,
            "IN": 95,
            "DE": 38,
            "BE": 17,
            "RS": 14,
            "IE": 12,
            "UA": 12
        },
        "total": 1534
    },
    "country_states_total": {
        "data": {
            "US": {
                "data": {
                    "ca": 4,
                    "fl": 1,
                    "ga": 1,
                    "il": 1,
                    "mn": 1,
                    "mo": 1,
                    "nc": 1,
                    "oh": 1
                },
                "total": 458
            },
            "FR": {
                "data": [],
                "total": 299
            },
            "GB": {
                "data": [],
                "total": 232
            },
            "ES": {
                "data": [],
                "total": 136
            },
            "IN": {
                "data": [],
                "total": 95
            },
            "DE": {
                "data": [],
                "total": 38
            },
            "BE": {
                "data": [],
                "total": 17
            },
            "RS": {
                "data": [],
                "total": 14
            },
            "IE": {
                "data": [],
                "total": 12
            },
            "UA": {
                "data": [],
                "total": 12
            }
        },
        "total": 1534
    },
    "languages_total": {
        "data": {
            "fr": 354,
            "en": 1180
        },
        "total": 1534
    },
    "sources_total": {
        "data": {
            "web": 304,
            "facebook": 0,
            "twitter": 672,
            "news": 339,
            "blogs": 146,
            "forums": 73
        },
        "total": 1534
    },
    "alert_id": 28222
}