API Endpoints

This RESTful API is intended to allow researchers and developers to access the data behind the Hedonometer. Twitter data is updated daily.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License Creative Commons License

If this work is used in academic publication, please use the following citation (provided in bibtex format):

@Misc{dodds2014a,
  author = 	 {Dodds, P. S. and Clark, E. M. and Desu, S. and Frank, M. R. and Reagan, A. J. and  Williams, J. R. and Mitchell, L. and Harris, K. D. and Kloumann, I. M. and Bagrow, J. P. and Megerdoomian, K. and McMahon, M. T. and Tivnan, B. F. and Danforth, C. M.},
  title = 	 {Human language reveals a universal positivity bias},
  OPThowpublished = {},
  OPTmonth = 	 {},
  year = 	 {2014},
  note = 	 {Preprint available at \href{http://arxiv.org/abs/1406.3855}{http://arxiv.org/abs/1406.3855}},
  OPTannote = 	 {}
}


Twitter Daily Timeseries




Example query and response:



http://hedonometer.org/api/v1/timeseries/?format=json&limit=3&offset=2100

{
    meta: {
	limit: 3,
	next: "?format=json&limit=3&offset=2103",
	offset: 2100,
	previous: "?format=json&limit=3&offset=2097",
	total_count: 2121
    },
    objects: [
	{
	    date: "2014-06-24T00:00:00",
	    happiness: "5.988"
	},
	{
	    date: "2014-06-25T00:00:00",
	    happiness: "5.998"
	},
	{
	    date: "2014-06-26T00:00:00",
	    happiness: "6.009"
	}
    ]
}

We are aware that the following days are missing from the dataset, due to either backend issues experienced by Twitter or missing data from our end:

  • 2012-04-22
  • 2009-12-18
  • 2009-12-19
  • 2009-12-20
  • 2009-08-03
  • 2009-08-04
  • 2009-08-05
  • 2009-05-19
  • 2009-05-18
  • 2009-05-17
  • 2009-05-16
  • 2009-05-15
  • 2009-05-14

LabMT Words




Example query and response, where we looking for words with happiness greater than 6, rank less than 500, and standard deviation less than 1, and limiting our result to the first three.



http://hedonometer.org/api/v1/words/?format=json&happs__gt=6&rank__lt=500&stdDev__lt=1&limit=3

{
    meta: {
	limit: 3,
	next: null,
	offset: 0,
	previous: null,
	total_count: 9
    },
    objects: [
	{
	    googleBooksRank: -1,
	    happs: 8.5,
	    lyricsRank: 1728,
	    newYorkTimesRank: -1,
	    rank: 1,
	    stdDev: 0.9313,
	    twitterRank: 3600,
	    word: "laughter"
	},
	{
	    googleBooksRank: 2458,
	    happs: 8.44,
	    lyricsRank: 1230,
	    newYorkTimesRank: -1,
	    rank: 2,
	    stdDev: 0.9723,
	    twitterRank: 1853,
	    word: "happiness"
	},
	{
	    googleBooksRank: 1372,
	    happs: 8.3,
	    lyricsRank: 375,
	    newYorkTimesRank: 1313,
	    rank: 4,
	    stdDev: 0.9949,
	    twitterRank: 65,
	    word: "happy"
	}
    ]
}

The API is searchable by word, happiness, rank, and standard deviation. To search any of these, append the URL option like in the above query, where the full set of Django model queries are available (see documentation).



Happiness by State in US New


Example query and response, where we looking for happiness in California on August 10, 2014.



http://hedonometer.org/api/v1/geohapps/?format=json&stateName=California&date=2014-08-10&stateId=5

{
    meta: {
	limit: 500,
	next: null,
	offset: 0,
	previous: null,
	total_count: 1
    },
    objects: [
	{
	    date: "2014-08-10T00:00:00",
	    happiness: "5.979",
	    stateId: 5,
	    stateName: "California"
	}
    ]
}

The API is searchable by state name, state ID, and date. To search any of these, append the URL option like in the above query, where again the full set of Django model queries are available (see documentation).