NB: This API is a work in progress.
Currently the Phreadz API offers the data required to build your own players and widgets based around the posts and conversations which Phreadz helps pull together.
Every 'channel', 'user' and 'post' on Phreadz currently outputs RSS, JSON and OPML data for applications to read and developers to build on.
You may access these data feeds for non-commercial uses only (please do not overload these urls with too many requests. Soon we will provide an API 'key', which will have limitations on the amount of requests which it can make.)
This API is currently read only. Details of the posting API will follow soon.
- rss : RSS data feed of post with all replies to post (and replies of replies) in reverse chronological order.
- json : JSON data feed of post data with list of replies to post (data object named: 'phreadz'). Includes data object containing named: 'post_path' of the contextual thread path leading to the post, if the post is not a 'top' post in a channel ('conversation starter').
The JSON data feed also supports jQuery developers by wrapping the data results in a function call by adding ?callback=foo to the url - where 'foo' is the name of the JavaScript function you want to call.
- opml : OPML data feed of post data and full thread structure of all replies and replies of replies.
- rss : RSS data feed of 20 recent posts by the user in reverse chronological order.
- json : JSON data feed containing user profile post data. Includes data object named: 'phreadz' containing data of last 20 posts by the user in reverse chronological order.
The JSON user data also supports the ability to add the 'page' query to the url to support pagination. eg : ?page=2 etc.
The JSON user data also supports jQuery developers by wrapping the data results in a function call by adding ?callback=foo to the url - where 'foo' is the name of the JavaScript function you want to call.
requires : channelname - channels are the subdomain of phreadz.com eg: 'tech', 'news', etc. The main 'lobby' channel name is 'www'.
format options (requires one)
- rss : RSS data feed of 20 recent posts in the channel in reverse chronological order.
- json : JSON data feed containing the channel intro post data. Includes data object named: 'phreadz' containing data of last 20 posts in the channel in reverse chronological order.
The JSON channel data also supports the ability to paginate results. Add page=# to the url to support pagination. eg : page=2 etc. (20 results per page)
The JSON channel data also supports the ability to filter 'top' posts only (the start of a thread) or only posts with replies
To list only the 'top' posts in a channel, add top=1 to your api url request
To list only the 'top' posts in a channel which have had a replies, add top=2 to your api url request
The JSON channel data also supports jQuery developers by wrapping the data results in a function call by adding ?callback=foo to the url - where 'foo' is the name of the JavaScript function you want to call.
POST HTML EMBED CODES
To get the html embed code for any post in a JSON object format, use:
http://api.phreadz.com/embed/[guid]/[format]/
requires:
- guid : The unique alphanumeric guid for the post.
- format : currently only supports 'json'. ['xml' to come soon.]
Provides a JSON object with one or two properties: 'html' and (if one exists) 'description'.
JSON OBJECT PROPERTIES
title : post title
in_channel : channel name
source : see below
link : URL link to standalone viewer
author : username
author_image_url : author profile image/avatar
guid : unique post ID
timestamp : UNIX timestamp of pubDate
pubDate : date of post in standard format: eg: Tue, 19 May 2009 02:26:07 +0100
replies : number of replies
hits : number of post hits/views (as a post is hit, a 30 min cookie is set to avoid recounts)
file_type : MIME type of the post media content
file_url : URL of the post media content
file_length : file size in bytes of the post media content
thumb_url : URL of thumbnail (if available) of the post media content
description : Body/description text of the post
post_code : special code used by email clients to send a reply to a post.
depending on the type of post or if it is a reply:
in_reply_to : unique post id of reply (if the post is a reply)
in_reply_to_user : username of reply_to post (if the post is a reply)
oembed : the html embed code required to display some post types from remote sites eg: YouTube, Vimeo, etc. - width and height variables are provided as "#WIDTH#" and "#HEIGHT#" so your code will need to replaces these strings with the desired display size.
current available values for 'source':
REC : video recorded using the Phreadz browser based recorder
FLV_URL : a remotely hosted Flash video file
MP3_URL : a remotely hosted mp3 audio file
TWELVE : a 12Seconds.tv video
BLIPTV : a Blip.tv video
SEESMIC : a Seesmic video
SLIDESHARE : a slideshare presentation
QIK : a Qik video
- The following sources are supported by the 'oembed' property, providing the full HTML embed code to the provider's host player as described above. In these cast the 'file_type' is set to 'oembed' in the main object.
OE_YOUTUBE : a YouTube Video
OE_BBCNEWS : a BBC News story video
OE_GVIDEO : a Google Video video
OE_FLICKR : a Flickr photo or video
OE_VIMEO : a Vimeo video
OE_VIDDLER : a Viddler video
OE_DMOTION : a DailyMotion video
OE_USTREAM : a UStream.tv recorded video show
OE_BLIPFM : a Blip.fm audio track (uses YouTube player if the track is video)
OE_FOD : a FunnyOrDie video
OE_CHUMOR : a CollegHumor video
OE_MYSPACE : a MySpace video
OE_FBOOK : a Facebook video
OE_ABC : an abc.com News video
OE_AUDIOBOO : an AudioBoo post (size depends on if there is an attached photo or not)
OE_ONION : an Onion News Network video
OE_FORATV : a fora.tv video
This API will be subject to improvements and additions.
