<< Back to Twitvid API Documentation
Authentication
Authentication is required to access the stream API. A client must
provide valid API key in 'token' field using GET or POST http methods.
To request an API key, please send an e-mail to support@twitvid.com explaining
how you plan to use the Stream API.
Access and Rate Limiting
Each API key allows to create only one standing connection to the
Streaming API. Excessive connection attempts,
regardless of success, will result in an automatic and temporary ban
of the client's IP address.
Connecting
To connect to the Streaming API, form a HTTP request and consume the
resulting stream. Our servers will hold the connection open
indefinitely.
Some HTTP client libraries only return the response body after the
connection has been closed by the server. These clients will not work
for accessing the Streaming API. You must use an HTTP client that will
return response data incrementally. Most robust HTTP client libraries
will provide this functionality. The Apache HttpClient will handle
this use case, for example.
Parsing Responses
The Streaming API returns data in XML and JSON formats.
Parsing JSON responses from the Streaming API is simple: every object
is returned on its own line, and ends with a carriage return.
Streams may also contain video deletion notices. Clients are urged to
honor deletion requests and discard deleted videos immediately. At
times, video deletion messages may arrive before the video.
XML: <delete><guid>12345</guid><
username>user</username></delete>
JSON: { "delete": { "guid": 12345, "username": 'user' } }
API Usage
URL: http://stream.twitvid.com/api/
Formats: xml, json
Method(s): GET,POST
Parameters: events
Returns: stream of video elements
Response sample
<?xml version="1.0" encoding="UTF-8"?>
<video>
<guid>12345</guid>
<source>The source of the upload. Could be 'web' , 'Tweetie', etc.</source>
<event> event_id at zvents.com. A twitvid can be tagged if captured from an event </event>
<longitude> long if user has consented to supply their location</longitude>
<num_followers> num of followers the user has </num_followers>
[coming soon] <num_generated_views> The number of views the user has generated through his uploaded twitvids to date </num_generated_views>
[coming soon] <num_generated_likes> The number of likes the user's videos have received on all their uploaded twitvids to date </num_generated_likes>
[coming soon] <num_generated_comments> The number of comments the user's videos have generated on all their uploaded twitvids to date </num_generated_comments>
</user>
</video>
For delete events:
{ "delete": { "guid": 12345, "username": 'user' } }
For comment events
{ "comment": {
"guid": "12345",
"user" : {
"name": "username",
"location": "twitter user location here",
"profile_image_url": "http://twitvid-image-cache.s3.amazonaws.com/profile_images/username.jpg",
"profile_background_image_url": "http://twitvid-image-cache.s3.amazonaws.com/background_images/username.gif",
"description": "twitter user bio here",
"num_followers": "num of followers the user has",
[coming soon] "num_generated_views": "The number of views the user has generated through his uploaded twitvids to date",
[coming soon] "num_generated_likes": "The number of likes the user's videos have received on all their uploaded twitvids to date",
[coming soon] "num_generated_comments": "The number of comments the user's videos have generated on all their uploaded twitvids to date"
},
"comment": "Hello" } }
Query Parameters
Allows client to filter returned elements. Can be 'upload' to receive
only video elements, or 'delete' to receive only delete elements, or 'comment'
to receive only comments. A combination can be formed by a logical Or, such as
'upload|comment'
Error Messages
When the Stream API returns error messages, it does so in your
requested format. For example, an error from an XML method might look
like this:
<?xml version='1.0' encoding='UTF-8'?>
<rsp status='fail'>
<err code='1001' msg='Invalid or expired token'/>
</rsp>
<< Back to Twitvid API Documentation
Comments (0)
You don't have permission to comment on this page.