API Formats

The Tweetworks API can send data in either XML or JSON. All the URLs in this document assume you'll be using XML, but if you would prefer to receive JSON formatted data, just replace the extension ("xml") with "json".

If you would like to use callback methods with JSON, just provide the name of the callback in a query parameter called "jsonp". Similary, if you would like the return data to be wrapped in script tags, provide the query parameter "script". For example:

http://tweetworks.com/posts/index/newest.json?jsonp=My.callback&script=

If these parameters are not provided, the API will return standard JSON.

Sending data

All relevant data in a POST body must be enclosed in a "data" envelope. For example:

data[key]=keyval&data[Post][body]=posttext&data[Post][sendToTwitter]=1

This is what the POST body would look like when using the Post::add method to create a new post in the public stream. Note that the API key and Post data are all enclosed in the data envelope.

API keys

Every request to the Tweetworks Web API must contain a valid API key in the POST body's data envelope. If you do not have an API key, please contact us to request one.

Once you've received your Tweetworks Web API key, add it to each POST body's data envelope with the varname "key":

data[key]=keyval

Authentication

Many methods require user authentication. This is always handled by basic HTTP authentication with a user's Twitter username and password. The realm for HTTP authentication is "Login please".

While asking users for their login information, we ask that you provide a link to our Terms of Use page. This is especially important if the user hasn't logged into Tweetworks before. Our Terms of Use page can be found here: http://tweetworks.com/pages/terms

Errors

If the API encounters an error from any request, it will return an XML error container with cdata text describing the nature of the error that occurred. For example:

<error><text><![CDATA[Flagrant System Error!]]></text></error>

As with other methods, the JSON equivalent returns exactly the same structure in the JSON format. For example:

{"error":{"text":"Flagrant System Error!"}}

Post Methods

By default, most Post methods retrieve discussions in descending order, newest (most recently created) first. To retrieve the most recently contributed-to discussions first instead, swap the "newest.xml" portion of the URL for "updated.xml".

Lists of posts are limited to 20 items per request. To paginate through these list, simply specify the page number as a variable in the URL of the request, for example:
http://tweetworks.com/posts/index.xml?page=2
Alternatively, specify a post ID to retrieve the next block of posts before or after a certain post. For example:
http://tweetworks.com/posts/index.xml?beforeId=12071
http://tweetworks.com/posts/index.xml?afterId=12071

It is also possible to attach a search query to most Post retrieval methods using the "q" parameter. For example:
http://tweetworks.com/posts/index.xml?q=Tweetworks
http://tweetworks.com/posts/group/Tweetworks140/newest.xml?q=Facebook

Post Return Data

Expect Post methods to return data in the following format:

posts: [
	{
		id:         [numeric, ID for this post],
		user_id:    [numeric, ID for user who posted
		            message],
		group_id:   [numeric, ID for group post was
		            submitted to, or empty if public],
		parent_id:  [numeric, ID of parent post if this is
		            a reply],
		twitter_id: [numeric, ID of this post on
		            Twitter],
		bingo:      [boolean, 1 if this is a "bingo" post,
		            empty otherwise],
		body:       [cdata, text body of post],
		created:    [cdata, timestamp of post creation time],
		group:      [see groups return data],
		user:       [see users return data],
		replies:    [numeric, number of replies to a
		            discussion]
	} //, ... (variable number of posts)
]

For XML, each post is contained inside a "post" tag.

The "posts" container is present even when only one post is returned.

Group Methods

Lists of groups are limited to 30 items per request. To paginate through these list, simply specify the page number as a variable in the URL of the request, for example:
http://tweetworks.com/groups/index.xml?page=2

Group Return Data

Expect Group methods to return data in the following format:

groups: [
	{
		id:          [numeric, ID for this group],
		name:        [cdata, name of group],
		private:     [boolean, 1 if this group is private,
		             empty otherwise],
		description: [cdata, group description]
		keywords: [cdata, group keywords]
	} //, ... (variable number of groups)
]

For XML, each group is contained inside a "group" tag.

The "groups" container is present even when only one group is returned.

User Methods

Lists of users are limited to 30 items per request. To paginate through these list, simply specify the page number as a variable in the URL of the request, for example:
http://tweetworks.com/users/index.xml?page=2

User Return Data

Expect User methods to return data in the following format:

users: [
	{
		id:         [numeric, ID for this user],
		username:   [cdata, screen name of user],
		avatar_url: [cdata, URL to obtain user avatar],
		name:       [cdata, name of user],
		twitter_id: [numeric, Twitter ID for this user]
	} //, ... (variable number of users)
]

For XML, each user is contained inside a "user" tag.

The "users" container is present even when only one user is returned.