Stream Meta API

Provides information about and derived from the entities in a stream.

All streams have, by default, a set of meta information captured about them as they live. Most notably, this information includes:

This basic/standard meta information is commonly used to render such visualizations as counters, progress meters, and social poll results.

Additionally, there are advanced features that may be enabled on a stream-by-stream basis by Spredfast administrators. These features include:

This advanced stream meta information is commonly used to render various leaderboard visualizations.

Resource URL

http://api.massrelevance.com/:account/:stream_name/meta.:format

The components of this URL are:

Example URL: http://api.massrelevance.com/MassRelDemo/kindle/meta.json

Parameters

Standard

These parameters control the information you get back in the basic/standard meta response.

num_minutes
optional
Number of minutes of activity to include
Type: integer
Default: 60
Example Value: 120
Notes: Must be > 0. Only affects activity counts, not advanced features
num_hours
optional
Number of hours of activity to include
Type: integer
Default: 24
Example Value: 6
Notes: Must be > 0. Only affects activity counts, not advanced features
num_days
optional
Number of days of activity to include
Type: integer
Default: 365
Example Value: 30
Notes: Must be > 0. Only affects activity counts, not advanced features
activity
optional
Include activity and count properties in response
Type: bit
Default: 1
Example Value: 0
Notes: Included/on by default
finish
optional
Unix time of the point of which activity data should end. This will be reflected by the value of the last item of the minute activities.
Type: integer
Default: now
Example Value: 1349278694
Notes: Only use the seconds portion of unix time (JavaScript will give use the number in milliseconds. Divide by 1000). . Only affects activity counts, not advanced features
networks
optional
Include networks property in the response, which is an array of strings. Returns one string for each network that is used as a source in the stream.
Type: boolean
Default: disabled
Example Value: 1
Notes: Any non-empty value is sufficient

Top Retweeted Tweets

This is an advanced feature2.

These parameters control the information you get back when requesting the top retweeted tweets in a stream.

Note: a Tweet must be retweeted at least 3 times in order to be considered a top retweet.

top_periods
optional
Include top tweets from specific hourly periods provided. "a" is all time. "2012070412" is July 4, 2012 at 12PM UTC.
Type: string(ish)
Default: a (all-time)
Example Value: a,2012070412
Notes: Accepts a string list delimited by commas. All hours specified will be in UTC and formatted as yyyyMMddHH (Java SimpleDateFormat pattern). Either top_periods or top_periods_relative can be used per request.
top_periods_relative
optional
Include top tweets from specific hourly periods ago from now. "0" is right now. "1" is one hour ago.
Type: integer(s)
Default: N/A
Example Value: 1,2,3
Notes: Accepts an integer list delimited by commas. Either top_periods or top_periods_relative can be used per request.
top_count
optional
Number of tweets to include per period
Type: integer
Default: 5
Example Value: 12
Notes: Max value of 20

Top Hashtags

This is an advanced feature2.

These parameters control the information you get back when requesting the top discovered hashtags in a stream.

num_hashtags
optional
Number of discovered hashtags to return.
Type: integer
Default: 10
Example Value: 5

Top Links

This is an advanced feature2.

These parameters control the information you get back when requesting the top discovered URLs/links in a stream.

num_links
optional
Number of discovered URLs/links to return.
Type: integer
Default: 10
Example Value: 5

Top Contributors

This is an advanced feature2.

(Twitter only) This feature tracks the Twitter users whose tweets have been retweeted or replied to the most within the stream.

These parameters control the information you get back when requesting the top contributors in a stream.

num_contributors
optional
Number of contributor user handles return.
Type: integer
Default: 10
Example Value: 5

Top Topics

These parameters control the information you get back when requesting the top topics in a stream.

Two sets of topics are returned: top and total. The top section returns the topics with the highest count over the last minute (with single minute counts), whereas the total section returns all-time count.

num_trends
optional
Number of topics (buckets) to return
Type: integer
Default: 30
Example Value: 5
Notes: Affects both `top` and `total`.
sort
optional
Determines the sort order for returned topics
Type: string
Default: count desc
Example Value: position asc
Possible Values: count desc, count asc, position desc, position asc
Notes: position asc returns topics in the order they have been configured within Experiences. If matching configuration is important, we recommend using sort=position asc in conjunction with all_topics=1 (below)
all_topics
optional
Returns all topics, not just those with count > 0
Type: integer
Default: 0
Example Value: 1
Notes: By default, only topics with count > 0 are included in the response. Use all_topics=1 to retrieve all topics regardless of count
percent
optional
Returns percentages (pct) in buckets (total group only, not top). Use all_topics=1 when using percent, as the percentage is calculated from the sum of all returned topics.
Type: integer
Default: 0
Example Value: 1
Possible Values: 1
precision
optional
Determines the number of decimal places to return in percentages.
Type: integer
Default: 0
Example Value: 1
Possible Values: 0, 1, 2, 3, 4
disregard
optional
Exclude trends that match supplied values from buckets while trying to ensure `num_trends` is met
Type: strong
Default: N/A
Example Value: obama,romney
Notes: Accepts a string list delimited by commas

Example Requests

Standard Meta Information

To get a stream's basic/standard count and activity rate information:

$ curl http://api.massrelevance.com/MassRelDemo/kindle/meta.json

The response:

{
  "name": "kindle",
  "full_name": "MassRelDemo/kindle",
  "description": "The Twitterverse has some good things to say about the Amazon Kindle.",
  "created_at": "2010-09-21T19:18:20Z",
  "count": {
    "total": 19958828,
    "rejected": 14238898,
    "pending": 5704155,
    "approved": 15775
  },
  {
    "minute": {  // arrays of minute-by-minute counts
      "total": [],
      "rejected": [],
      "pending": [],
      "approved": []
    },
    "hourly": { // arrays of hour-by-hour counts
      "total": [],
      "rejected": [],
      "pending": [],
      "approved": []
    },
    "daily": { // arrays of day-by-day counts
      "total": [],
      "rejected": [],
      "pending": [],
      "approved": []
    }
  }
}

The arrays of minute-by-minute, hour-by-hour, and day-by-day counts are sorted oldest to newest. The last array item contains the count for the most recent complete period. The second-to-last item contains the count for the period before that, and so on.

By default, minute count arrays contain the most recent 60 complete one-minute periods, hourly count arrays contain the most recent 24 complete one-hour periods, and daily count arrays contain the most recent 365 complete one-day periods.

Minute, hourly, and daily periods begin and end as per the clock, not on a rolling basis:

Advanced Meta Information

A stream with other advanced features enabled will have far more information contained in its meta response.

$ curl http://api.massrelevance.com/MassRelDemo/things-we-do/meta.json

The response:

{
  // standard details
  "name": "things-we-do",
  "full_name": "MassRelDemo/things-we-do",
  "description": "This is what people are doing on Twitter.",
  "created_at": "2012-09-26T15:07:07Z",
  "count": {
    "total": 6210,
    "rejected": 314,
    "pending": 1260,
    "approved": 4636
  },
  "activity": {
    "daily": {},
    "hourly": {},
    "minute": {}
  },

  // top retweeted tweets
  "top": {},

  // a description of the time periods that have been returned in the above 'top' object
  "top_periods": [],

  // top hashtags
  "hashtags": [],

  // top links
  "links": [],

  // top contributors
  "contributors": [],

  // top topics
  "buckets": {},

}

Advanced Meta Information: Top Retweeted Tweets

Get the top retweeted tweets in this stream.

$ curl http://api.massrelevance.com/MassRelDemo/things-we-do/meta.json?top_periods=a,20120926,2012092616&top_count=3

In this example, we're asking for the top 3 retweeted tweets in each for 3 specific time periods: all-time in this stream ('a'), within a specific day (Sept 26, 2012), and within a specific hour of that day (UTC 16:00, Sept 26, 2012).

The response:

{
  // ... for this example, other meta details have been removed ...

  // top retweeted tweets
  "top": {
    "20120926": [
      {
        // ...top retweeted tweet 1 of the UTC Day Sept 26, 2012...
      },
      {
        // ...top retweeted tweet 2...
      },
      {
        // ...top retweeted tweet 3...
      }
    ],
    "2012092616": [
      {
        // ...top retweeted tweet 1 of the 16:00 UTC Hour Sept 26, 2012...
      },
      {
        // ...top retweeted tweet 2...
      },
      {
        // ...top retweeted tweet 3...
      }
    ],
    "a": [
      {
        // ...top retweeted tweet 1 of all time in this stream...
      },
      {
        // ...top retweeted tweet 2...
      },
      {
        // ...top retweeted tweet 3...
      }
    ]
  },

  // a description of the time periods that have been returned in the above 'top' object
  "top_periods": [
    "a",
    "20120926",
    "2012092616"
  ]
}

Advanced Meta Information: Top Hashtags

Get the top discovered hashtags in this stream.

$ curl http://api.massrelevance.com/MassRelDemo/things-we-do/meta.json?num_hashtags=5

The count indicated in the response indicates the number of approved entities in the last hour using that hashtag.

The response:

{
  // ... for this example, other meta details have been removed ...

  // top hashtags
  "hashtags": [
    {
      "hashtag": "callmeoldfashioned",
      "count": 2409
    },
    {
      "hashtag": "m312",
      "count": 911
    },
    {
      "hashtag": "oomf",
      "count": 385
    },
    {
      "hashtag": "imhappiestwhen",
      "count": 385
    },
    {
      "hashtag": "lwwy",
      "count": 380
    }
  ]
}

Advanced Meta Information: Top Links

Get the top discovered links in this stream.

$ curl http://api.massrelevance.com/MassRelDemo/things-we-do/meta.json?num_links=5

The count indicated in the response indicates the number of approved entities in the last 18 hours containing that link.

The response:

{
  // ... for this example, other meta details have been removed ...

  // top links
  "links": [
    {
      "count": 2194,
      "link": "http://youtu.be/jvHE70LZEOA"
    },
    {
      "count": 1079,
      "link": "http://viddy.it/PGptsX"
    },
    {
      "count": 360,
      "link": "http://www.spredfast.com"
    },
    {
      "count": 300,
      "link": "http://x.co/oFxV"
    },
    {
      "count": 287,
      "link": "http://twitpic.com/ay2x06"
    }
  ]
}

Advanced Meta Information: Top Contributors

Get the top contributors in this stream.

$ curl http://api.massrelevance.com/MassRelDemo/things-we-do/meta.json?num_contributors=5

The count indicated in the response indicates the number of approved entities in the last week containing that user's handle (@name).

The response:

{
  // ... for this example, other meta details have been removed ...

  // top links
  "contributors": [
    {
      "count": 39668,
      "name": "@techcrunch"
    },
    {
      "count": 21641,
      "name": "@mashable"
    },
    {
      "count": 8373,test
      "name": "@intel"
    },
    {
      "count": 2768,
      "name": "@wired"
    },
    {
      "count": 2518,
      "name": "@drizzled"
    }
  ]
}

Advanced Meta Information: Top Topics

Get the top constrained topics in this stream.

$ curl http://api.massrelevance.com/MassRelDemo/things-we-do/meta.json?num_trends=5

The count indicated in the response indicates the total number of approved entities all-time and average thing per minute counts over the last 10 minutes containing that topic's keywords.

The response:

{
  // ... for this example, other meta details have been removed ...

  // top topics
  "buckets": {
    "top": [],
    "total": []
  }
}