Leaderboard APIs

Leaderboard visualizations display lists of ranked "things". These ranked "things" could be actual entities (e.g. the "Top Tweets" template within Spredfast Experiences), configured topics ("Top Topics"), users ("Top Influencers"), or other pieces of information such as URLs or hashtags mentioned within Tweets.

Each Leaderboard API provides the top occurring "things" of the requested type, along with the aggregate counts of each "thing" over a given time range (within a single stream). Unless otherwise noted, all counts are derived from approved entities.

Use of these APIs is preferred over use of similar features in the Stream Meta API.

The following types of "things" are supported:

Notes:

Resource URLs

http://api.massrelevance.com/:account/:stream_name/top_[thing].json

Examples:

Parameters

For all of the endpoints listed above, the following parameters are applicable:

Example Requests

Top Hashtags over the timespan starting 24 hours ago and ending 12 hours ago, bucketed into 1 hour groups:

http://api.massrelevance.com/massreldemo/amazing-text/top_hashtags.json?start=-24h&finish=-12h&resolution=1h

Top Terms over the timespan starting 12 hours ago and ending now, bucketed into 30 minute groups:

http://api.massrelevance.com/massreldemo/amazing-text/top_terms.json?start=-12h&resolution=30m

Top URLs over the timespan starting 1 hour ago and ending now, bucketed into 5 minute groups:

http://api.massrelevance.com/massreldemo/amazing-text/top_urls.json?start=-1h&resolution=5m

Example Responses

Top Hashtags

curl http://api.massrelevance.com/massreldemo/amazing-text-retweets/top_hashtags.json?start=-1h&finish=-30m&resolution=5m&limit=2

{
  "resolution": "5m",
  "finish": 1403037000,
  "start": 1403035200,
  "data": [
    {
      "things": [
        {
          "type": "hashtag",
          "thing": "1N1T"
        },
        {
          "type": "hashtag",
          "thing": "MEX"
        }
      ],
      "start": 1403035200
    },
    {
      "things": [
        {
          "type": "hashtag",
          "thing": "1N1T"
        },
        {
          "type": "hashtag",
          "thing": "MEX"
        }
      ],
      "start": 1403035500
    },
    {
      "things": [
        {
          "type": "hashtag",
          "thing": "1N1T"
        },
        {
          "type": "hashtag",
          "thing": "GTLT"
        }
      ],
      "start": 1403035800
    },
    {
      "things": [
        {
          "type": "hashtag",
          "thing": "1N1T"
        },
        {
          "type": "hashtag",
          "thing": "MEX"
        }
      ],
      "start": 1403036100
    },
    {
      "things": [
        {
          "type": "hashtag",
          "thing": "1N1T"
        },
        {
          "type": "hashtag",
          "thing": "WorldCup2014"
        }
      ],
      "start": 1403036400
    },
    {
      "things": [
        {
          "type": "hashtag",
          "thing": "1N1T"
        },
        {
          "type": "hashtag",
          "thing": "MEX"
        }
      ],
      "start": 1403036700
    }
  ]
}

Top Terms

curl http://api.massrelevance.com/massreldemo/amazing-text-retweets/top_terms.json?start=-1h&finish=-30m&resolution=5m&limit=2

{
  "resolution": "5m",
  "finish": 1403037300,
  "start": 1403035500,
  "data": [
    {
      "things": [
        {
          "type": "term",
          "thing": "thanks"
        },
        {
          "type": "term",
          "thing": "team"
        }
      ],
      "start": 1403035500
    },
    {
      "things": [
        {
          "type": "term",
          "thing": "thanks"
        },
        {
          "type": "term",
          "thing": "team"
        }
      ],
      "start": 1403035800
    },
    {
      "things": [
        {
          "type": "term",
          "thing": "thanks"
        },
        {
          "type": "term",
          "thing": "team"
        }
      ],
      "start": 1403036100
    },
    {
      "things": [
        {
          "type": "term",
          "thing": "thanks"
        },
        {
          "type": "term",
          "thing": "team"
        }
      ],
      "start": 1403036400
    },
    {
      "things": [
        {
          "type": "term",
          "thing": "ochoa"
        },
        {
          "type": "term",
          "thing": "mexico"
        }
      ],
      "start": 1403036700
    },
    {
      "things": [
        {
          "type": "term",
          "thing": "mexico"
        },
        {
          "type": "term",
          "thing": "summer"
        }
      ],
      "start": 1403037000
    }
  ]
}

Top User Mentions

curl http://api.massrelevance.com/massreldemo/amazing-text-retweets/top_user_mentions.json?start=-1h&finish=-30m&resolution=5m&limit=2

{
  "resolution": "5m",
  "finish": 1403037300,
  "start": 1403035500,
  "data": [
    {
      "things": [
        {
          "type": "user_mention",
          "thing": "JozyAltidore"
        },
        {
          "type": "user_mention",
          "thing": "DrakeBell"
        }
      ],
      "start": 1403035500
    },
    {
      "things": [
        {
          "type": "user_mention",
          "thing": "NiallOfficial"
        },
        {
          "type": "user_mention",
          "thing": "JozyAltidore"
        }
      ],
      "start": 1403035800
    },
    {
      "things": [
        {
          "type": "user_mention",
          "thing": "DrakeBell"
        },
        {
          "type": "user_mention",
          "thing": "JozyAltidore"
        }
      ],
      "start": 1403036100
    },
    {
      "things": [
        {
          "type": "user_mention",
          "thing": "DrakeBell"
        },
        {
          "type": "user_mention",
          "thing": "NiallOfficial"
        }
      ],
      "start": 1403036400
    },
    {
      "things": [
        {
          "type": "user_mention",
          "thing": "DrakeBell"
        },
        {
          "type": "user_mention",
          "thing": "Realmadridplace"
        }
      ],
      "start": 1403036700
    },
    {
      "things": [
        {
          "type": "user_mention",
          "thing": "DrakeBell"
        },
        {
          "type": "user_mention",
          "thing": "NiallOfficial"
        }
      ],
      "start": 1403037000
    }
  ]
}