We Feel Fine API

"Bad artists copy. Great artists steal."
       - Pablo Picasso

Borrowing is a great tradition in art; each individual piece of art is part of a larger conversation. With technology-based art, we have the ability to enable borrowing more directly by opening up APIs to our work. Accordingly, we have opened up an API for We Feel Fine, to allow other artists to more easily make pieces that explore these human emotions. Since we are borrowing from the feelings of thousands of people across the world to make our piece, we find it fitting for other artists to be able to borrow from our work to make theirs. We are eager to see where this conversation will take us.

The API is free under the Creative Commons Attribution-NonCommercial-Sharealike license and is documented below.

 

Documentation

Required:

Base URL: http://api.wefeelfine.org:8080/ShowFeelings?

returnfields – comma delimited list of all the data you want to get back. Options are:

  • imageid (used to get images)
  • feeling (sad, depressed, happy, etc. – full list of valid feelings is here)
  • sentence (the full sentence that went with the feeling)
  • posttime (epoch timestamp of the time the post was scraped)
  • postdate (YYYY-MM-DD of the day the post was scraped)
  • posturl (the url of the post)
  • gender (1 (male) or 0 (female))
  • born (YYYY from when the user was born)
  • country (country of the user)
  • state (state of the user)
  • city (city of the user)
  • lat (latitude of the user's city)
  • lon (longitude of the user's city)
  • conditions (the weather when the post was written in that city)
    • 1 = sunny
    • 2 = rainy
    • 3 = snowy
    • 4 = cloudy

Optional:

  • feeling – specify the feeling you want returned (sad, happy, depressed, etc. – full list of valid feelings is here)
  • gender – specify the gender you want returned (1=male, 0=female)
  • agerange – specify the age range of the user you want returned (0 = 0-9, 10 = 10-19, 20 = 20-29, etc.)
  • conditions – specify the weather you want returned (1=sunny, 2=rainy, 3=snowy, 4=cloudy)
  • country – specify the country you want returned (united states, france, etc.)
  • state – specify the state you want returned (new york, California, etc)
  • city – specify the city you want returned (tokyo, los angeles, etc.)
  • postdate – specify the specific day you want returned (YYYY-MM-DD)
  • postmonth – specify the month you want returned (M or MM)
  • postyear – specify the year you want returned (YYYY)
  • limit – specify the number of feelings you want returned (1000, 20, etc.) (The maximum limit is 1500. Any limit specified above that will return 1500 feelings.)
  • extraimages – specify the number of extra images you want returned (20, 70, etc)
  • display – if you specify display=text, it will give you plain text. Otherwise, the display will be xml.

 

Sample queries:

"Give me the most recent 50 sentences"
http://api.wefeelfine.org:8080/ShowFeelings?display=xml&returnfields=
sentence&limit=50

"Give me the most recent 500 feelings"
http://api.wefeelfine.org:8080/ShowFeelings?display=xml&returnfields=
imageid,feeling, sentence,posttime,postdate,posturl,gender,born,country,
state,city,lat,lon,conditions&limit=500

"Give me the most recent 500 feelings, with 50 extra images"
http://api.wefeelfine.org:8080/ShowFeelings?display=xml&returnfields=
imageid,feeling,sentence,posttime,postdate,posturl,gender,born,country,
state,city,lat,lon,conditions&limit=500&extraimages=50

"Give me the most recent 500 feelings from women in Tokyo who feel sad, and give me 50 extra images too"
http://api.wefeelfine.org:8080/ShowFeelings?display=xml&returnfields=
imageid,feeling,sentence,posttime,postdate,posturl,gender,born,country,
state,city,lat,lon,conditions&feeling=sad&city=tokyo&limit=500&extraimages=50

"Give me 50 sentences from Valentine's day"
http://api.wefeelfine.org:8080/ShowFeelings?display=xml&returnfields=
sentence&postdate=2006-02-14&limit=50

"Give me 50 sentences from Valentine's day from people who feel loved"
http://api.wefeelfine.org:8080/ShowFeelings?display=xml&returnfields=
sentence&postdate=2006-02-14&feeling=loved&limit=50

 

Retrieving images

Function to get an image's URL based on a postdate and an imageid:

// Form full image url
String getImgPath(String postdate, String imageid, String imagesize){
    String imgpath = "http://images.wefeelfine.org/data/images/ ";
    imgpath += postdate.replace('-','/');
    imgpath += "/"+imageid;
    if(imagesize == "thumb") imgpath += "_thumb.jpg";
    else imgpath += "_full.jpg";
    return imgpath;
}

 

Returned XML samples:

<feeling feeling="sad" sentence="i still feel sad and heartbroken from the crying" posttime="1146809001" postdate="2006-05-04" posturl=" http://super8mama.livejournal.com/29964.html" born="1967" gender="1" country="united states" state="california" city="san francisco" lat=" 37.759881" lon="-122.437392" conditions="4" />

<feeling imageid="15098" feeling="sad" sentence="i feel sad for some of them and for some i do not have much feeling sort of a neutral feeling not happy but not too sad as if they were some strangers i don't know" posttime="1129507200" postdate="2005-10-17" posturl=" http://jaderays.blogspot.com/2005/10/let-it-go.html" country="united states" state="california" />

 

License

The API is free under the Creative Commons Attribution-NonCommercial-Sharealike license ( http://creativecommons.org/licenses/by-nc-sa/2.5/ ).

Sites that use this API must provide attribution by including the following html on their site:

Powered by: <a href= http://www.wefeelfine.org>We Feel Fine</a>.

Since this is a free API and we're paying for the bandwidth out of our own pockets, we'll ask you to throttle your API queries at a maximum of 4 requests per minute. (For most applications, one request evey few minutes should be enough). If your application is too hungry, we may block your IP so the rest of the applications using the API can be fed. We'll turn you back on if you e-mail us nicely at someone@wefeelfine.org and promise to keep at 4 requests per minute or less.