Stream.get

From Facebook Developer Wiki

Jump to: navigation, search

Contents

Description

This method returns an object (in JSON-encoded or XML format) that contains the stream from the perspective of a specific viewer/user.

If you specify only one user ID in the source_ids array, you can return, at minimum, the last 50 posts from that user's profile stream (Wall) for the last 180 days (it likely can be more). If you specify more than one user ID in the source_ids array, you can return posts in those streams only from the last few days (about one week).

You can filter the stream in a number of ways:

  • By limiting the stream to a specific set of source_ids (user IDs, Page IDs, group IDs, or event IDs).
  • By start and end times.
    Note: Posts are always retrieved in reverse chronological order (that is, starting with the most recent and returning backwards) with the most recent being limited by end_time and the oldest being limited by start_time (if either or both are specified), up to the total number of posts specified by the limit parameter. For example, if you specify a start_time that happens to include 15 posts but you also specify limit=10 and no end_time, you'll retrieve the 10 most recent posts, not the 10 following start_time.
  • By the total number of posts you want to return.
  • By the user's filters. You can determine the filters using stream.getFilters or querying the stream_filter FQL table. Filters can be user-defined, Facebook-defined (like News Feed/nf or networks), or for applications (app_<APPLICATION ID>).

Before you can get data from a user's stream, you need the extended permission read_stream.

Parameters

RequiredNameTypeDescription
required session_key string The session key of the logged in user, or the session key provided when the user granted your application the offline_access extended permission. The session key is automatically included by our PHP client.
optional viewer_id int The user ID for whom you are fetching stream data. You can pass 0 for this parameter to retrieve publicly viewable information. However, desktop applications must always specify a viewer as well as a session key. (Default value is the current session user.)
source_ids array An array containing all the stream data for the user profiles, Pages, groups, and events connected to the viewer_id. You can filter the stream to include posts by the IDs you specify here. (Default value is all connections of the viewer.)
start_time time The earliest time (in Unix time) for which to retrieve posts from the stream. The start_time uses the updated_time field in the stream (FQL) table as the baseline for determining the earliest time for which to get the stream. (Default value is 1 day ago.)
end_time time The latest time (in Unix time) for which to retrieve posts from the stream. The end_time uses the updated_time field in the stream (FQL) table as the baseline for determining the latest time for which to get the stream. (Default value is now.)
limit int A 32-bit int representing the total number of posts to return. (Default value is 30 posts.)
filter_key string A filter associated with the user. Filters get returned by stream.getFilters or the stream_filter FQL table. To filter for stream posts from your application, look for a filter with a filter_key set to "app_YOURAPPLICATIONID".
metadata array A JSON-encoded array in which you can specify one or more of the following when you call stream.get:
  • albums -- to request the user's aid (album ID)
  • profiles -- to request the user's ID (user ID or Page ID)
  • photo_tags to request the user's pid (photo ID)
  • strip_tags(field) -- to strip out any HTML markup and encoding in an attachment field. You can specify this function more than once if you want to remove markup from multiple fields.
These parameters are all optional. (Default value is false for all keys.)

Example Requests

$facebook->api_client->stream_get(viewer_id, source_ids, start_time, end_time, limit, filter_key, metadata);


To return your application's stream for a given user, do the following

$facebook->api_client->stream_get('','','','','','app_YOURAPPLICATIONID','');

Response

This method returns a JSON-encoded or XML object containing the following arrays:

  • posts, which is an array of post data, containing the fields defined by the stream (FQL) table.
  • profiles, which is an array of profile information, containing the fields defined by the profile (FQL) table.
  • albums, which is an array of album information, containing the field as defined by the album (FQL) table.

FQL Equivalent

FQL queries take the form: SELECT <fields> FROM <table> WHERE <conditions>

This function is similar to doing the following FQL query, with the appropriate parameters specified (note you can SELECT any fields from the stream (FQL) table):

SELECT comments, likes FROM stream WHERE post_id=182032615385

Error Codes

For a complete list of error codes, see Error codes.

Notes

You can call this method using a session secret, and not the application secret (for example, for a Facebook Connect site or desktop application).

See Also

Retrieved from "http://wiki.developers.facebook.com/index.php/Stream.get"