HarvardTweets API

on the CS50 Wiki

Jump to: navigation, search

The HarvardTweets API allows you to request data programmatically from HarvardTweets in CSV, JSON, JSONP, serialized PHP, or RSS format. The API provides a RESTful interface, which means that you can query it using simple HTTP GET requests.

HarvardTweets knows about tweets from 2009-10-05 through the current date. New tweets may take up to five minutes to appear in HarvardTweets's database.

Contents

Author

To report bugs or request features, contact:

David J. Malan '99
http://www.cs.harvard.edu/malan/

License

Use of this API is governed by a Creative Commons Attribution-Noncommerical 3.0 Unported license, which means that you may use its data for non-commercial purposes so long as you attribute your data to this API, as by including a link to HarvardTweets in your own work. For approval of commercial purposes, contact the author.

Methods

tweeters

To query the HarvardTweets API for tweeters, contact the server via URLs in this format: 

http://tweets.cs50.net/api/1.1/tweeters?param1=value1&param2=value2&...

Supported parameters include:

parameter description
callback Required iff output is jsonp. Callback function with which response will be padded.
output Required. Format for output. Must be csv, json, jsonp, or php.
screen_name Optional. A comma-separated list of Twitter screen names.

If any parameters are malformed or any required parameters are omitted, an empty response will be returned along with, possibly, HTTP status code 400 Bad Request.

CSV

If you request tweeters in CSV format (e.g., http://tweets.cs50.net/api/1.1/tweeters?screen_name=asellerg,harvard&output=csv), the response will be a series of comma-delimited rows, per the below: 

screen_name,name,url,description,profile_image_url
asellerg,"Andrew Sellergren",,,http://s.twimg.com/a/1258674567/images/default_profile_6_normal.png
Harvard,"Harvard University",http://harvard.edu,"Highlighting advances in teaching and research excellence across Harvard University",http://a1.twimg.com/profile_images/228702720/Mod_Color_Harvard_Shield_small_bigger_normal.jpg

Note that the response's first row defines the CSV file's fields. Fields' order may change over time, so do not hardcode indices into your own code. Use that first row to determine fields' indices dynamically, per this article on parsing CSV.

JSON

If you request tweeters in JSON format (e.g., http://tweets.cs50.net/api/1.1/tweeters?screen_name=asellerg,harvard&output=json), the response wil be an array of objects, per the below: 

[
   {
      "screen_name":"asellerg",
      "name":"Andrew Sellergren",
      "url":"",
      "description":"",
      "profile_image_url":"http:\/\/s.twimg.com\/a\/1258674567\/images\/default_profile_6_normal.png"
   },
   {
      "screen_name":"Harvard",
      "name":"Harvard University",
      "url":"http:\/\/harvard.edu",
      "description":"Highlighting advances in teaching and research excellence across Harvard University",
      "profile_image_url":"http:\/\/a1.twimg.com\/profile_images\/228702720\/Mod_Color_Harvard_Shield_small_bigger_normal.jpg"
   }
]

JSONP

If you request tweeters in JSONP format (e.g., http://tweets.cs50.net/api/1.1/tweeters?screen_name=asellerg,harvard&output=jsonp&callback=parseResponse), the response wil be an array of objects, per the below: 

parseResponse([{"screen_name":"asellerg","name":"Andrew Sellergren","url":"","description":"","profile_image_url":"http:\/\/a3.twimg.com\/profile_images\/604140089\/ls_5276_lance7_normal.jpg"},{"screen_name":"Harvard","name":"Harvard University","url":"http:\/\/harvard.edu","description":"Highlighting advances in teaching and research excellence across Harvard University","profile_image_url":"http:\/\/a1.twimg.com\/profile_images\/228702720\/Mod_Color_Harvard_Shield_small_bigger_normal.jpg"}])

PHP

If you request tweeters in serialized PHP format (e.g., http://tweets.cs50.net/api/1.1/tweeters?screen_name=asellerg,harvard&output=php), the response will be a serialized array of associative arrays, per the below: 

a:2:{i:0;a:5:{s:11:"screen_name";s:8:"asellerg";s:4:"name";s:17:"Andrew Sellergren";s:3:"url";s:0:"";s:11:"description";s:0:"";s:17:"profile_image_url";s:67:"http://s.twimg.com/a/1258674567/images/default_profile_6_normal.png";}i:1;a:5:{s:11:"screen_name";s:7:"Harvard";s:4:"name";s:18:"Harvard University";s:3:"url";s:18:"http://harvard.edu";s:11:"description";s:83:"Highlighting advances in teaching and research excellence across Harvard University";s:17:"profile_image_url";s:93:"http://a1.twimg.com/profile_images/228702720/Mod_Color_Harvard_Shield_small_bigger_normal.jpg";}}

Once you unserialize that response, you'll have the below in memory: 

Array
(
    [0] => Array
        (
            [screen_name] => asellerg
            [name] => Andrew Sellergren
            [url] => 
            [description] => 
            [profile_image_url] => http://s.twimg.com/a/1258674567/images/default_profile_6_normal.png
        )
 
    [1] => Array
        (
            [screen_name] => Harvard
            [name] => Harvard University
            [url] => http://harvard.edu
            [description] => Highlighting advances in teaching and research excellence across Harvard University
            [profile_image_url] => http://a1.twimg.com/profile_images/228702720/Mod_Color_Harvard_Shield_small_bigger_normal.jpg
        )
 
)

tweets

To query the HarvardTweets API for tweets, contact the server via URLs in this format: 

http://tweets.cs50.net/api/1.1/tweets?param1=value1&param2=value2&...

Supported parameters include:

parameter description
callback Required iff output is jsonp. Callback function with which response will be padded.
edt Optional. An end date/time in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format, where HH is in 24-hour time. (Don't overlook the T between YYYY-MM-DD and HH:MM:SS in the latter.) Tweets sent before or on this date/time will be returned. If omitted, no end date/time will be assumed.
from Optional. A comma-separated list of Twitter screen names.
q Optional. Query string. Supports quotes, +, and -. Be sure to URL-encode this parameter's value (as with PHP's urlencode). In particular, hashtags' hashes (#) should be encoded as %23.
sdt Optional. A start date/time in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format, where HH is in 24-hour time. (Don't overlook the T between YYYY-MM-DD and HH:MM:SS in the latter.) Tweets sent on or after this date/time will be returned. If omitted, the current date/time will be assumed.
to Optional. A comma-separated list of Twitter screen names.
output Required. Format for output. Must be csv, json, jsonp, php, or rss.

If any parameters are malformed or any required parameters are omitted, an empty response will be returned along with, possibly, HTTP status code 400 Bad Request.

Responses include no more than 256 tweets.

CSV

If you request tweets in CSV format (e.g., http://tweets.cs50.net/api/1.1/tweets?from=asellerg&output=csv), the response will be a series of comma-delimited rows, per the below: 

id,from_user,to_user,text,created_at
4589094829,asellerg,coleironman,"@coleironman Yeah, man, she's a beaut!  You around this week (before Thursday) to go for a ride?",2009-10-03T18:30:22
4572116596,asellerg,,"http://twitpic.com/k1tcd - Race tomorrow.",2009-10-03T00:24:40

Note that the response's first row defines the CSV file's fields. Fields' order may change over time, so do not hardcode indices into your own code. Use that first row to determine fields' indices dynamically, per this article on parsing CSV.

JSON

If you request tweets in JSON format (e.g., http://tweets.cs50.net/api/1.1/tweets?from=asellerg&output=json), the response wil be an array of objects, per the below: 

[
   {
      "id":"4589094829",
      "from_user":"asellerg",
      "to_user":"coleironman",
      "text":"@coleironman Yeah, man, she's a beaut!  You around this week (before Thursday) to go for a ride?",
      "created_at":"2009-10-03T18:30:22"
   },
   {
      "id":"4572116596",
      "from_user":"asellerg",
      "to_user":"",
      "text":"http:\/\/twitpic.com\/k1tcd - Race tomorrow.",
      "created_at":"2009-10-03T00:24:40"
   }
]

JSONP

If you request tweets in JSONP format (e.g., http://tweets.cs50.net/api/1.1/tweets?from=asellerg&output=jsonp&callback=parseResponse), the response wil be an array of objects, per the below: 

parseResponse([{"id":"4589094829","from_user":"asellerg","to_user":"coleironman","text":"@coleironman Yeah, man, she's a beaut!  You around this week (before Thursday) to go for a ride?","created_at":"2009-10-03T18:30:22"},{"id":"4572116596","from_user":"asellerg","to_user":"","text":"http:\/\/twitpic.com\/k1tcd - Race tomorrow.","created_at":"2009-10-03T00:24:40"}])

PHP

If you request tweets in serialized PHP format (e.g., http://tweets.cs50.net/api/1.1/tweets?from=asellerg&output=php), the response will be a serialized array of associative arrays, per the below: 

a:2:{i:0;a:5:{s:2:"id";s:10:"4589094829";s:9:"from_user";s:8:"asellerg";s:7:"to_user";s:11:"coleironman";s:4:"text";s:96:"@coleironman Yeah, man, she's a beaut!  You around this week (before Thursday) to go for a ride?";s:10:"created_at";s:19:"2009-10-03T18:30:22";}i:1;a:5:{s:2:"id";s:10:"4572116596";s:9:"from_user";s:8:"asellerg";s:7:"to_user";s:0:"";s:4:"text";s:41:"http://twitpic.com/k1tcd - Race tomorrow.";s:10:"created_at";s:19:"2009-10-03T00:24:40";}}

Once you unserialize that response, you'll have the below in memory: 

Array
(
    [0] => Array
        (
            [id] => 4589094829
            [from_user] => asellerg
            [to_user] => coleironman
            [text] => @coleironman Yeah, man, she's a beaut!  You around this week (before Thursday) to go for a ride?
            [created_at] => 2009-10-03T18:30:22
        )
 
    [1] => Array
        (
            [id] => 4572116596
            [from_user] => asellerg
            [to_user] => 
            [text] => http://twitpic.com/k1tcd - Race tomorrow.
            [created_at] => 2009-10-03T00:24:40
        )
 
)

Examples

See Also

Related APIs

External Links

Changelog

  • 1.0
  • 1.1
    • Added support for JSONP.
Retrieved from "http://wiki.cs50.net/HarvardTweets_API"
Personal tools