The DataTweet API Response format The form of the response to a successful call is a JSON string of the form {"result":<theResult>,"status":200} If an error occurs the response will have the form: {"error":<errorMessage>,"status":<statusCode>,"details":<JSON_Object>} Error messages are succinct and stable. Status is an integer that indicates the category of error using HTTP status codes. The actual HTTP status code, as opposed to the value of the status field in the returned content, is always 200. The optional details field has a form which depends on the call and the error. JSONP If an HTTP GET argument of the form callback=<functionName> is included, then the response object will be wrapped as follows: <functionName>(<response>) This supports the JSONP technique. GET methods A JSON representation of a DataTweet resource is requested by including the HTTP GET argument format=json in a URL that would otherwise return a HTML page representing the resource. For the moment, this is only supported for URLs of the form http://www.datatweet.net/tw/<username>/Stream/<streamName>/select()?<arguments> but will apply to more resources in the near future. Example call: Arguments to the select() call: where string Conditions on tweets which must be met. Example: where=distanceMiles("Portland,OR",45.52,-122.67)<=1000 and 4<=magnitude The edit filter option on any data stream page provides a user interface for building suitable values of the where input. Here are the rules: the where input has the form: clause0 and clause1 ... and clauseN Clauses have the one of the forms: <fieldName> <operator> <value> <value> <operator> <fieldName> where <operator> is "=", "<=", or ">=" for real or integer fields, and "=" for other types of fields. A clause of the form: distanceMiles("<address>",<latitude>,<longitude>) <= <distance> is also supported if the tweet type includes latitude and longitude fields. The <address> input is not used in the calculation, and is optional. Although DataTweet performs geocoding in the context of interactive use, it does not presently support geocoding as part of the API due to licensing restrictions on the Google geocoder. outputs string A comma separated list of fields to be included. Example: outputs=magnitude,region,depth limit integer How many tweets to return. The default is 20, and the maximum 100 Returns: A JSON encoded array of Tweets Error conditions: the stream does not exist. Error message: "notFound". Status: 404 Authentication For methods that require authentication, an API key is required: Each method requiring authentication should include the following arguments: user string Your Twitter user name key string Your DataTweet API key POST methods http://api.datatweet.net/tw/<userName>/Stream/<streamName>/insert() Arguments: tweets string A JSON-encoded array of tweets to be added. Example:
[{"magnitude":1.7,"depth":13.6,"region":"Central California","latitude":36.494734,"longitude":-120.137558}, Effect: inserts the Tweet into the indicated data stream. The properties of the tweets must match the type associated with the stream. See the help section on Publishing for details. Error conditions: The stream does not exist. Error message: "notFound". Status: 404 Ill-formed tweets, or tweets which do not match the stream's type. Error message: "badTweet". Status: 406. Details:If there is one or more type mismatch among the tweets, this will be an array of objects, of the form exemplified by: {"tweet":{"mmgnitude":2.2,"depth":"quite deep"},"index":1,"errors":["No such field: mmgnitude","depth is not a real"]} Rate Limits The default limit for inserts is 360 Tweets per stream per hour, and 60 per individual API call. Please contact us if you need your limit bumped. |