The Twinfluence API

Here you'll find documentation for a simple XML API interface for accessing twinfluence.com data, designed to be loosely consistent with the twitter.com REST API for XML requests.

Requirements of Usage

By using the API, you agree to not abuse it, simple as that, with my own subjective opinion being the sole determinant of what constitutes "abuse". That being said, as long as you aren't trying to steal the entire contents of the twinfluence database for your own nefarious purposes, aren't reselling the information, and aren't using the twinfluence API as a way to get around the Twitter.com API, I probably won't care. If you abuse it - and I do log IP addresses and account names - you will be banned from the twinfluence API. If the abuse gets out of hand by too many users, I'll take the API offline, simple as that. I'm doing this as a service to the twitter community, so let's not ruin it for everybody.

By using this API, you also agree to visibly give credit to, and a link to, twinfluence.com on every page in which you publish twinfluence data. Use your own judgement, but basically give credit where it's due.

HTTP Return Codes

• 200: Processed without errors
• 401: Authentication failure; Twitter.com could not validate the supplied credentials.
• 404: Not found; we couldn't find the target id as a valid Twitter.com user.
• 413: Request too large; the target id has too many followers to process as a live HTTP/ API request.
• 502: Twitter.com gateway error; you probably exceeded your hourly Twitter.com API limit for the credentials you provided.
• 503: Twitter.com overload; we're getting the API version of the dreaded "Fail Whale"!

Protocol: User Data

Upon success, returns a page of twinfluence and twitter data on for the requested twitter user ID. Requires the following HTTP POST variables:
 

HTTP POST Variables

• URL: http://twinfluence.com/api_user.php
• user: The twitter screen name of the authenticating requestor.
• pwd: The twitter password for the authenticating requestor.
• id: The twitter screen name of the targeted twitter user, for which twinfluence data is requested.
• cacheonly: (Optional). If this is set to "TRUE", only cached results will be provided, even if the cached results are potentially quite old. This will speed up API response on IDs with very large follower counts (in fact, users with 30,000+ followers will be queued for offline processing and won't be sent at all to prevent timeout errors). If omitted, the twinfluence API will attempt to recalculate the requested target's data before sending.

Protocol: Search

Upon success returns a list of users matching search criteria. This can be particularly useful for creating custom, ranked lists based upon Twitter users' descriptions and locations. Requires the following HTTP POST variables:

• URL: http://twinfluence.com/api_search.php
• user: The twitter screen name of the authenticating requestor.
• pwd: The twitter password for the authenticating requestor.
• des: A comma-delimited list of keywords to filter users' "description" field against. Note, these keywords will be compiled with a boolean "or" SQL search statement. Optional (default is no filter).
• loc: A comma-delimited list of keywords to filter users' "location" field against. Note, these keywords will be compiled with a boolean "or" SQL search statement. Optional (default is no filter).
• sort: The twinfluence metric by which the list is sorted. Acceptable values include "SECONDORDER" (reach, the default value), "FIRSTORDER" (friends_count), "VELOCITY", "CENTRALIZATION", and "SOCIAL_CAPITAL" (case insensitive). Optional.
• limit: The maximum number of search results (users) to return. The default (and maximum) is 25. Optional.
• minfollows: Filters search results by users with the stated minimum number of followers. Default is 1 (optional).

Search results are always loaded from cached (databased) values. Search results are provided in the requested order, but are not numbered or assigned a rank value based upon your arbitrary search criteria; your code will have to assign rank scores if desired (eg #1, #2, #3 etc.). A correctly formatted unix command for recreating the "top 5 social capital" list on the Twinfluence home page may resemble curl --data "user=your_screen_name&pwd=your_password&sort=social_capital&limit=5&minfollows=100" --url "http://twinfluence.com/api_search.php".