| title | class | side_content |
|---|---|---|
Stream Meta API |
guide |
<h2><a href="#ref-top">Stream Meta API</a></h2> <h3><a href="#ref-resource-url">Resource URL</a></h3> <h3><a href="#ref-params">Parameters</a></h3> <ul>
<li><a href="#ref-params-standard">Standard (Counts and Activity)</a></li>
<li><a href="#ref-params-top-retweeted-tweets">Top Retweeted Tweets</a></li>
<li><a href="#ref-params-top-hashtags">Top Hashtags</a></li>
<li><a href="#ref-params-top-links">Top Links</a></li>
<li><a href="#ref-params-top-contributors">Top Contributors</a></li>
<li><a href="#ref-params-top-topics">Top Topics</a></li>
<li><a href="#ref-params-top-moments">Top Moments</a></li>
</ul> <h3><a href="#ref-reqs">Example Requests</a></h3> <ul>
<li><a href="#ref-reqs-standard">Standard (Counts and Activity)</a></li>
<li><a href="#ref-reqs-top-retweeted-tweets">Top Retweeted Tweets</a></li>
<li><a href="#ref-reqs-top-hashtags">Top Hashtags</a></li>
<li><a href="#ref-reqs-top-links">Top Links</a></li>
<li><a href="#ref-reqs-top-contributors">Top Contributors</a></li>
<li><a href="#ref-reqs-top-topics">Top Topics</a></li>
<li><a href="#ref-reqs-top-moments">Top Moments</a></li>
</ul>
|
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...
- counts: total number of entities in a stream, split by their moderation state (pending, approved, rejected)
- activity: arrays of per-minute, per-hour, and per-day counts
This basic/standard meta information is commonly used to render such visualizations as counters, progress meters, and social poll results.
Additionally, on a stream-by-stream basis, there are many advanced features that may be turned on (by Mass Relevance administrators). These features include...
- top retweeted tweets: (Twitter only) the tweets in a stream that have been retweeted the most
- top hashtags: the hashtags that have been used the most over the last hour
- top links: the URLs that have been referenced the most over the last 18 hours
- top contributors: (Twitter only) the Twitter users whose tweets have been retweeted or replied to the most within the stream
- top topics: a tally of the number of times that specific keyword sets have been mentioned in the stream
- top moments: an extension to top topics, capturing the minutes (moments) when individual topics peaked in activity
This advanced stream meta information is commonly used to render various leaderboard visualizations.
http://tweetriver.com/:account/:stream_name/meta.:format
The components of this URL are:
- account: the stream owner's account name (e.g.
bdainton) - stream_name: the name of the stream (e.g.
kindle) - format:
json,xml1
Example URL: http://tweetriver.com/bdainton/kindle/meta.json
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
|
|
num_hours
optional
|
Number of hours of activity to include
Type: integer
Default: 24
Example Value: 6
Notes: Must be > 0
|
|
num_days
optional
|
Number of days of activity to include
Type: integer
Default: 365
Example Value: 30
Notes: Must be > 0
|
|
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).
|
This is an advanced feature2.
These parameters control the information you get back when requesting the top retweeted tweets in a stream.
|
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 pattern3). 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
|
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
|
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
|
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
|
This is an advanced feature2.
These parameters control the information you get back when requesting the top topics in a stream.
|
num_trends
optional
|
Number of trends to return in response per bucket
Type: integer
Default: 30
Example Value: 5
Notes: 5
|
|
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
|
This is an advanced feature2.
These parameters control the information you get back when requesting the top moments in a stream.
|
top_moments
optional
|
Include moments 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 pattern3). Either `top_moments` or `top_moments_relative` can be used per request.
|
|
top_moments_relative
optional
|
Include moments 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_moments` or `top_moments_relative` can be used per request.
|
|
top_moments_count
optional
|
Number of moments to include per period
Type: integer
Default: 1
Example Value: 5
|
To get a stream's basic/standard count and activity rate information...
$ curl http://tweetriver.com/bdainton/kindle.json
The response:
```json
{
"name": "kindle",
"full_name": "bdainton/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": []
}
}
}
A stream with other advanced features enabled will have far more information contained in its meta response.
$ curl http://tweetriver.com/MassRelDemo/things-we-do/meta.json
The response:
```json
{
// 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": {},
// top moments
"moments": {},
// a description of the time periods returned in the above 'moments' object
"moments_periods": []
}
Get the top retweeted tweets in this stream.
$ curl http://tweetriver.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:
```json
{
// ... 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"
]
}
Get the top discovered hashtags in this stream.
$ curl http://tweetriver.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:
```json
{
// ... 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
}
]
}
Get the top discovered links in this stream.
$ curl http://tweetriver.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:
```json
{
// ... 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.massrelevance.com"
},
{
"count": 300,
"link": "http://x.co/oFxV"
},
{
"count": 287,
"link": "http://twitpic.com/ay2x06"
}
]
}
Get the top contributors in this stream.
$ curl http://tweetriver.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:
```json
{
// ... 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"
}
]
}
Get the top constrained topics in this stream.
$ curl http://tweetriver.com/MassRelDemo/things-we-do/meta.json?num_trends=5
The count indicated in the response indicates the number of approved entities all-time and in the last 10 minutes containing that topic's keywords.
The response:
```json
{
// ... for this example, other meta details have been removed ...
// top topics
"buckets": {
"top": [],
"count": []
}
}
Get the top moments in the stream.
$ curl http://tweetriver.com/MassRelDemo/things-we-do/meta.json?top_moments=a&top_moments_relative=1,2
The count indicated in the response indicates the number of approved entities all-time and in the last 10 minutes containing that topic's keywords.
The response:
```json
{
// ... for this example, other meta details have been removed ...
// top moments
"moments": {
// TODO
}
}
- Footnote1 -- Our docs only cover the
jsonAPI, but thexmlendpoint supports the same query parameters as thejsonendpoint and a similar response to thejsonendpoint. - Footnote2: -- This feature is enabled on a stream by stream basis, by a Mass Relevance administrator (upon request). By default, this feature is not enabled.
- Footnote3 -- I like Android's docs better for this class than Oracle's.