Stream API

Provides approved status entities from a stream sorted from most recently approved to least recently approved (in most cases, this is reverse chronological order).

Displaying Status Entities

Special care must be taken when displaying status entities.

To access data from the API, a customer must have accepted Spredfast Experiences's API usage agreement for a given stream. This includes agreeing to comply with Twitter's Display Requirements and Guidelines for using Tweets in broadcast when displaying Twitter statuses.

Twitter Display Requirements
https://dev.twitter.com/terms/display-requirements

Twitter Guidelines for using Tweets in broadcast
https://support.twitter.com/articles/114233-guidelines-for-using-tweets-in-broadcast

Resource URL

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

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

Parameters

Standard

limit
optional
Number of status entities to return.
Type: integer
Default: 50
Example Value: 100
Notes: Max value of 200
since_id
optional
Includes only those status entities approved after supplied status entity_id biasing towards real-time. Note: make sure you use entity_id. see entity_id vs. id_str
Type: string
Default: N/A
Example Value: 255682528302747648
Notes: API will return from the newest status entity to the supplied entity (but not including) or until limit is reached. Usage of since_id, from_id, and start_id is mutually exclusive; only one of these parameters may be used in a single request.
from_id
optional
Includes only those status entities approved after supplied status entity_id without skipping over status entities. It is noteworthy that since_id is preferred in most instances. Note: make sure you use entity_id. see entity_id vs. id_str
Type: string
Default: N/A
Example Value: 255682528302747648
Notes: API will return from the newest status entity to the supplied entity (but not including) or until limit is reached. Usage of since_id, from_id, and start_id is mutually exclusive; only one of these parameters may be used in a single request.
start_id
optional
Includes only those status entities approved before supplied status entity_id. This parameter is commonly used to implement 'More' functionality on a stream of content, wherein an end user sees a stream of content, then clicks on a 'More' link to display the next N entities. By supplying the entity_id of the last viewed entity, you may request the set of entities that came before it in the stream. Note: make sure you use entity_id. see entity_id vs. id_str
Type: string
Default: N/A
Example Value: 255682528302747648
Notes: Usage of since_id, from_id, and start_id is mutually exclusive; only one of these parameters may be used in a single request. This parameter also has an alias: start.
callback
optional
Enables JSONP support. Wraps JSON response with a JavaScript function of given name.
Type: string
Default: N/A
Example Value: myFunction
Notes: Only supported by the json endpoint. jsonp is a supported alias.
geo_hint
optional
When possible, geo_hint adds inferred status entity location from the authoring user's profile information. The data is added the to geo_hint property of a Twitter status entity.
Type: bit
Default: 0
Example Value: 1
Notes: Only for Twitter statuses. More info below.
page_links
optional
Includes any Pages that are currently linked to the entity. The data is added the to massrel/page_links property of an entity.
Type: bit
Default: 0
Example Value: 1
More info below.
replies
optional
Includes the status entity that a status entity replied to. The status entity is added to the in_reply_to property of a status entity.
Type: bit
Default: 0
Example Value: 1
network
optional
Includes entities from a specified social network only.
Type: string
Default: N/A (all content returned)
Example Value: twitter
Possible Values: twitter, facebook, instagram, google_plus, rss
Notes: Must be a single value (`network=twitter`); multiple values (`network=`twitter,facebook`) are not supported.
include_entities
optional
XML endpoint only. Includes an `entities` object on Tweets containing links, media, or other references.
Type: integer
Default: 0 (`entities` object not returned)
Example Value: 1
Possible Values: 0, 1
Notes: Applies to XML endpoint only.

Advanced

reverse
optional
Reverses the status entities in response to be in chronological approved order (default is reverse chronological approved order) so that entities approved earlier are on top.
Type: bit
Default: 0
Example Value: 1
Notes: Only the returned set of statuses is reversed.
strip_links
optional
Removes trailing URLs from the text of a status entity.
Type: bit
Default: 0
Example Value: 1
Notes: Only for on-air/broadcast displays.
keywords
optional
Returns only entities containining the specified keywords.
Type: string
Default: N/A
Example Value: democrat%20republican
Notes: See additional usage notes below.
from
optional
Returns only entities that authored by the specified author.
Type: string
Default: N/A
Example Value: jack
Notes: For Twitter and Instagram content, query using the user's handle. For Facebook and Google+ content, use the user's ID (as names from those networks are non-unique). See additional usage notes below.
timeframe[start]
optional
Returns only items created after given time. see Advanced timeframe parameter
Type: integer
Default: N/A
Example Value: 1380666060
Notes: Only use the seconds portion of unix time (JavaScript will give the number in milliseconds. Divide by 1000).
timeframe[finish]
optional
Returns only items created before given time. see Advanced timeframe parameter
Type: integer
Default: N/A
Example Value: 1380666060
Notes: Only use the seconds portion of unix time (JavaScript will give the number in milliseconds. Divide by 1000).

Advanced keywords parameter

Returns only entities that contain the specified keywords.

Examples:

Note: %2B is the URL escaped "+", and %23 is the URL escaped "#".

Advanced from parameter

Returns only entities from a specific account.

Examples: - from=massrelevance - Contains entities from massrelevance

Note: When both the keywords and from params are used together, they are ANDed together. keywords=curation&from=spredfast will return entities created by massrelevance that contain the word "curation". For Twitter and Instagram content, query using the user's handle. For Facebook and Google+ content, use the user's ID (as names from those networks are non-unique).

Advanced timeframe parameter

Returns entities created in a given time range.

$ curl http://api.massrelevance.com/MassRelDemo/kindle-tf.json?timeframe[start]=1400755580&timeframe[end]=1400784970

Best Practices

Notes

Timeframe Differences

entity_id vs. id_str

entity_id and id_str might be the same or similar values, but each has different purposes.

When using the stream API, the entity_id MUST be used for use with Spredfast Experiences API URL parameters. It is an internal indentifier that might evolve as Spredfast's architecture changes.

id_str MUST be used when linking and visualizing Tweet's in HTML. e.g when linking to Twitter https://twitter.com/spredfast/status/{{id_str}}. This is an indentifier that Twitter gives a Tweet and all references to Twitter MUST use this value.

Example Requests

Standard Stream Information

The response is a JSON array. If no entities are available, then the response will be an empty JSON array. If an error occurs then the response will be empty (whitespace).

Example Request

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

[
 // this is a Tweet/Status response
 // https://dev.twitter.com/docs/api/1/get/statuses/show/%3Aid
 {
    // data added by Spredfast
    // mostly useless or for backwards compatibility
    "chained_stream_id": null,
    "adhoc_for_stream_id": null,
    "requeued": null,
    "entity_id": "200249547354669056", // == id_str
    "order_id": "200249547354669056",  // == id_str
    "score": "200249547354669056",     // == id_str

    "created_at": "Wed May 09 15:43:07 +0000 2012",
    "id": 200249547354669060,
    "id_str": "200249547354669056",
    "text": "Love this! @NatalieCoughlin Profile - Swimming Video | NBC Olympics http://t.co/zgkQdeyG #2012Olympics #Olympics",
    "source": "<a href=\"http://twitter.com/tweetbutton\" rel=\"nofollow\">Tweet Button</a>",
    "truncated": false,
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
        "id": 20971136,
        "id_str": "20971136",
        "name": "Megan Coughlin",
        "screen_name": "MeganCoughlin",
        "location": "San Francisco, CA",
        "description": "SMB AE (midwest) at @InsideView, a Sales 2.0 company | Swimming Enthusiast | Gluten-free fanatic | http://www.linkedin.com/in/meganccoughlin ",
        "url": null,
        "protected": false,
        "followers_count": 641,
        "friends_count": 618,
        "listed_count": 9,
        "created_at": "Mon Feb 16 08:38:45 +0000 2009",
        "favourites_count": 0,
        "utc_offset": -32400,
        "time_zone": "Alaska",
        "geo_enabled": false,
        "verified": false,
        "statuses_count": 391,
        "lang": "en",
        "contributors_enabled": false,
        "is_translator": false,
        "profile_background_color": "709397",
        "profile_background_image_url": "http://a0.twimg.com/images/themes/theme6/bg.gif",
        "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme6/bg.gif",
        "profile_background_tile": false,
        "profile_image_url": "http://a0.twimg.com/profile_images/1780753484/headshot_normal.jpg",
        "profile_image_url_https": "https://si0.twimg.com/profile_images/1780753484/headshot_normal.jpg",
        "profile_link_color": "FF3300",
        "profile_sidebar_border_color": "86A4A6",
        "profile_sidebar_fill_color": "A0C5C7",
        "profile_text_color": "333333",
        "profile_use_background_image": true,
        "show_all_inline_media": false,
        "default_profile": false,
        "default_profile_image": false,
        "following": null,
        "follow_request_sent": null,
        "notifications": null
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 3,
    "entities": {
        "hashtags": [{
            "text": "2012Olympics",
            "indices": [
            89, 102]
        }, {
            "text": "Olympics",
            "indices": [
            103, 112]
        }],
        "urls": [{
            "url": "http://t.co/zgkQdeyG",
            "expanded_url": "http://www.nbcolympics.com/video/swimming/natalie-coughlin-profile-409643.html",
            "display_url": "nbcolympics.com/video/swimming…",
            "indices": [
            68, 88]
        }],
        "user_mentions": [{
            "screen_name": "NatalieCoughlin",
            "name": "Natalie Coughlin",
            "id": 26593416,
            "id_str": "26593416",
            "indices": [
            11, 27]
        }]
    },
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false
},


 // this is a Retweet response
 // it looks exactly like a normal tweet, except that it has the property `retweeted_status`
 // which is the original content that was retweeted
 //
 // https://dev.twitter.com/docs/api/1/get/statuses/show/%3Aid
 {
    // data added by Spredfast
    // mostly useless or for backwards compatibility
    "chained_stream_id": null,
    "adhoc_for_stream_id": null,
    "requeued": null,
    "entity_id": "192338599570702340", // == id_str
    "order_id": "192338599570702340",  // == id_str
    "score": "192338599570702340",     // == id_str

    "created_at": "Tue Apr 17 19:47:50 +0000 2012",
    "id": 192338599570702340,
    "id_str": "192338599570702336",
    "text": "RT @brainpicker: \"A fair and balanced guide to choosing between New York and San Francisco\" from @TheMorningNews http://t.co/KXaGg318",
    "source": "web",
    "truncated": false,
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
        "id": 8435702,
        "id_str": "8435702",
        "name": "Craig Richards",
        "screen_name": "donkeyattack",
        "location": "",
        "description": "I am the lineman for the county and I work at Twitter",
        "url": null,
        "protected": false,
        "followers_count": 1679,
        "friends_count": 1011,
        "listed_count": 47,
        "created_at": "Sun Aug 26 04:22:08 +0000 2007",
        "favourites_count": 384,
        "utc_offset": -18000,
        "time_zone": "Eastern Time (US & Canada)",
        "geo_enabled": false,
        "verified": false,
        "statuses_count": 1893,
        "lang": "en",
        "contributors_enabled": true,
        "is_translator": false,
        "profile_background_color": "E7C490",
        "profile_background_image_url": "http://a0.twimg.com/profile_background_images/379104346/Twitter_1544x2000.png",
        "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/379104346/Twitter_1544x2000.png",
        "profile_background_tile": true,
        "profile_image_url": "http://a0.twimg.com/profile_images/1680486414/craig3_bigger_normal.png",
        "profile_image_url_https": "https://si0.twimg.com/profile_images/1680486414/craig3_bigger_normal.png",
        "profile_banner_url": "https://si0.twimg.com/brand_banners/donkeyattack/1327518376/live",
        "profile_link_color": "FF0000",
        "profile_sidebar_border_color": "E7C490",
        "profile_sidebar_fill_color": "12E39D",
        "profile_text_color": "FF03FF",
        "profile_use_background_image": true,
        "show_all_inline_media": true,
        "default_profile": false,
        "default_profile_image": false,
        "following": null,
        "follow_request_sent": null,
        "notifications": null
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,

    // this is the original tweet that was retweeted
    // this content is the same as a normal tweet
    "retweeted_status": {
        "created_at": "Tue Apr 17 14:01:32 +0000 2012",
        "id": 192251451500789760,
        "id_str": "192251451500789760",
        "text": "\"A fair and balanced guide to choosing between New York and San Francisco\" from @TheMorningNews http://t.co/KXaGg318",
        "source": "<a href=\"http://bufferapp.com\" rel=\"nofollow\">Buffer</a>",
        "truncated": false,
        "in_reply_to_status_id": null,
        "in_reply_to_status_id_str": null,
        "in_reply_to_user_id": null,
        "in_reply_to_user_id_str": null,
        "in_reply_to_screen_name": null,
        "user": {
            "id": 9207632,
            "id_str": "9207632",
            "name": "Maria Popova",
            "screen_name": "brainpicker",
            "location": "Brooklyn, NY",
            "description": "Interestingness hunter-gatherer obsessed with combinatorial creativity. Editor of @brainpickings & @explorer. Bylines for @WiredUK & @TheAtlantic. MIT Fellow.",
            "url": "http://brainpickings.org",
            "protected": false,
            "followers_count": 178020,
            "friends_count": 307,
            "listed_count": 10405,
            "created_at": "Tue Oct 02 14:18:16 +0000 2007",
            "favourites_count": 12,
            "utc_offset": -18000,
            "time_zone": "Eastern Time (US & Canada)",
            "geo_enabled": true,
            "verified": false,
            "statuses_count": 50866,
            "lang": "en",
            "contributors_enabled": false,
            "is_translator": false,
            "profile_background_color": "FFDB00",
            "profile_background_image_url": "http://a0.twimg.com/profile_background_images/3864643/bg.jpg",
            "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/3864643/bg.jpg",
            "profile_background_tile": true,
            "profile_image_url": "http://a0.twimg.com/profile_images/125575833/twitter_normal.jpg",
            "profile_image_url_https": "https://si0.twimg.com/profile_images/125575833/twitter_normal.jpg",
            "profile_link_color": "990000",
            "profile_sidebar_border_color": "EBEAE5",
            "profile_sidebar_fill_color": "EBEAE5",
            "profile_text_color": "3F3F3F",
            "profile_use_background_image": true,
            "show_all_inline_media": true,
            "default_profile": false,
            "default_profile_image": false,
            "following": null,
            "follow_request_sent": null,
            "notifications": null
        },
        "geo": null,
        "coordinates": null,
        "place": null,
        "contributors": null,
        "retweet_count": 19,
        "entities": {
            "hashtags": [],
            "urls": [{
                "url": "http://t.co/KXaGg318",
                "expanded_url": "http://j.mp/HUBAOn",
                "display_url": "j.mp/HUBAOn",
                "indices": [
                96, 116]
            }],
            "user_mentions": [{
                "screen_name": "TheMorningNews",
                "name": "The Morning News",
                "id": 16539190,
                "id_str": "16539190",
                "indices": [
                80, 95]
            }]
        },
        "favorited": false,
        "retweeted": false,
        "possibly_sensitive": false
    },
    "retweet_count": 19,
    "entities": {
        "hashtags": [],
        "urls": [{
            "url": "http://t.co/KXaGg318",
            "expanded_url": "http://j.mp/HUBAOn",
            "display_url": "j.mp/HUBAOn",
            "indices": [
            113, 133]
        }],
        "user_mentions": [{
            "screen_name": "brainpicker",
            "name": "Maria Popova",
            "id": 9207632,
            "id_str": "9207632",
            "indices": [
            3, 15]
        }, {
            "screen_name": "TheMorningNews",
            "name": "The Morning News",
            "id": 16539190,
            "id_str": "16539190",
            "indices": [
            97, 112]
        }]
    },
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false
}]

Geo Hint Object

Example of a geo hinted object added on a Twitter status entity

{
    "geo_hint": {
        "country": "US",
        "state": "CA",
        "coordinates": [
          34.0522342, - 118.2436849]
    }
}

Page Links Object

Example of page_links property added on an entity

{
    ...
    "massrel": {
        "page_links": [
            {
                "id": 12,
                "url": "http://yoursite.com/yourpage",
                "short_url": "http://mssv.ly/13J39ai",
                "name": "Your page name",
                "description": "Your page description",
                "image_url": "http://yoursite.com/yourpage.jpg"
            }
        ]
    }
    ...
}