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 = 	 {}
}

Happiness Time Series

This is the API link: http://hedonometer.org/api/v1/happiness/?format=json&timeseries__title=en_all&date__gte=2019-01-01&limit=1000

You can also query the rt, no_rt versions:

Here’s the top of http://hedonometer.org/api/v1/happiness/?format=json&timeseries__title=en_all&date__gte=2019-01-01&limit=2

{
  "meta": {
    "limit": 2,
    "next": "/api/v1/happiness/?format=json&timeseries__title=en_all&date__gte=2019-01-01&limit=2&offset=2",
    "offset": 0,
    "previous": null,
    "total_count": 525
  },
  "objects": [
    {
      "date": "2020-03-19",
      "frequency": 239061347,
      "happiness": "5.748",
      "timeseries": "/api/v1/timeseries/3/"
    },
    {
      "date": "2020-03-20",
      "frequency": 236448165,
      "happiness": "5.774",
      "timeseries": "/api/v1/timeseries/3/"
    }
  ]
}

They all have the frequency, that’s the total word count.

Languages

In the above, en denoted english. The API also provide time series of happiness for each of the other langauges on hedonometer.org. To see which are available, look in the drop-down list on hedonometer.org. To the get the shortcode (en, es, etc), look in the URL for each of the time series visualizations after clickig the drop down link.

Using in Python

Example of pulling this down in Python:

import requests
import pandas as pd
import json
uri = 'http://hedonometer.org/api/v1/happiness/?format=json&timeseries__title=en_all&date__gte=2019-01-01&limit=1000'
r = requests.get(uri)
df = pd.DataFrame(json.loads(r.content)['objects'])
df.sort_values('date', inplace=True)
df.head()

The last line shows:

In [19]: df.head()
Out[19]:
    date    frequency happiness             timeseries
37  2019-01-01  145361578.0     6.095  /api/v1/timeseries/3/
38  2019-01-02  156353260.0     6.007  /api/v1/timeseries/3/
39  2019-01-03  161389001.0     6.002  /api/v1/timeseries/3/
40  2019-01-04  163318124.0     5.983  /api/v1/timeseries/3/
41  2019-01-05  159511070.0     5.984  /api/v1/timeseries/3/
Known issues

The following days may be 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

Events

If you want the annotated events, they are available as well:

http://hedonometer.org/api/v1/events/?format=json&happs__timeseries__title=en_all&happs__date__gte=2020-05-15&limit=1000

(set the date back to 2019-01-01 or whenever you want them starting at).

Here’s what you get from the events api:

{
  "meta": {
    "limit": 1000,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "happs": {
        "date": "2020-05-26",
        "frequency": 249581473,
        "happiness": "5.870",
        "timeseries": "/api/v1/timeseries/3/"
      },
      "id": 733,
      "importance": 5,
      "longer": "Murder of George Floyd during arrest in Minnesota",
      "resource_uri": "/api/v1/events/733/",
      "shorter": "Murder of,George Floyd",
      "wiki": "https://en.wikipedia.org/wiki/Death_of_George_Floyd",
      "x": -35,
      "y": 30
    },
    {
      "happs": {
        "date": "2020-05-29",
        "frequency": 344542921,
        "happiness": "5.659",
        "timeseries": "/api/v1/timeseries/3/"
      },
      "id": 735,
      "importance": 100,
      "longer": "Protests of police violence in response to the death of George Floyd",
      "resource_uri": "/api/v1/events/735/",
      "shorter": "Protests of,police violence",
      "wiki": "https://en.wikipedia.org/wiki/Twin_Cities_protests",
      "x": -50,
      "y": 50
    }
  ]
}

LabMT Words

A table of words (downloadable as csv, excel) are available for each language by using the "words" dropdown in the menu bar at the top of the page. There are many languages and lists available, with an example query and result available for each on that page.

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