The Truthy API

We have a very large collection of tweets -- a random sample of approximately 8% of the entire Twitter stream.

However, we organize and make available only a subset of tweets, those related to politics, social movements, and/or news. Our filtering system bundles these tweets into Memes (#hashtags, @usernames, http://urls, and "phrases"). We do this by compiling a list of keywords such as politician's names, words like "vote," or popular hashtags and looking for them in tweets. When a tweet is found with one of these keywords, we identify the memes in that tweet to be about the topic.

In this API, you will have access to a list of the memes we have observed along with some general statistics and social network layouts. Here, we will outline a few tutorials on how to access the data and statistics through the Python module.

Example Query

The following query will retrieve all of the memes that contain the word "obama" and have at least 30 unique contributing users.

response = Unirest.get(
  "https://truthy-public.p.mashape.com/memes?text__icontains=obama&num_users__gt=30",
  {
    "X-Mashape-Authorization": "YOUR MASHAPE KEY HERE"
  });

Response

For each response, there are two primary fields: meta and objects tag. The meta tag gives you important information such as the total number of results that satisfy the query; the limit per page; and the current offset.

Example:

print response.body
==>
{'meta': {'limit': 1000,
          'next-offset': 1000,
          'offset': 0,
          'total_count': 222916},
 'objects': [{'id': 15,
             'img': 'http://carl.cs.indiana.edu/truthy/networks/15.png',
             'last_event_ts': '2013-04-14T11:50:25',
             'meme_type': 'hash_tag',
             'num_tweets': 369628, 
             'num_users': 199759,
             'text': '#obama'},
              ...
            ]}

Retrieving Results

Each response's object field is a list of the results for which you queried. You can access this in python by accessing the body field in the response object.

Example:

memes = response.body["objects"]
print memes[0]
==> 
  {'id': 15,
   'img': 'http://carl.cs.indiana.edu/truthy/networks/15.png',
   'last_event_ts': '2013-04-14T11:50:25',
   'meme_type': 'hash_tag',
   'num_tweets': 369628,
   'num_users': 199759,
   'text': '#obama'}

Pagination

A query may have many hundreds or thousands of pages. To go to the next page, you can modify your previous query's offset parameter to what is found in meta's next-offset field.

Example:

next_offset = resp.body["meta"]["next-offset"]
response = Unirest.get(
  "https://truthy-public.p.mashape.com/memes?text__icontains=obama&num_users__gt=30&offset=%s" % (next_offset),
  {
    "X-Mashape-Authorization": "YOUR MASHAPE KEY HERE"
  });
obama_memes = resp.body["objects"]

Please cite the following publication when using this data

Truthy: enabling the study of online social networks. Karissa Rae McKelvey, and Filippo Menczer. CSCW Companion, page 23-26. ACM, (2013) PDF: http://arxiv.org/pdf/1212.4565v2.pdf Cite: http://www.bibsonomy.org/bibtex/2104d2f95d3abad77e44fdefc67c1b1c3/dblp

Last 7 days, UTC

Average Latency
26ms

Average Uptime
100.0%

Current Status
Online

  • No information
  • Outage
  • Disruption
  • Normal
Average latency determined from Mashape to API Response time

Endpoints

HTTP 200 : Memes GET/memes
						{
  "img": "String Value",
  "last_event_ts": "String Value",
  "meme_type": "String Value",
  "num_tweets": 10,
  "num_users": 10,
  "resource_uri": "String Value",
  "text": "String Value"
}						
Memes

Statistics about Memes (#hashtag, @user, http://url, or "phrase") for the past 90 days of Twitter communication.


Test console
Description
Parameter
string

Restricts the return query to those memes that contain the given text. Case insensitive.
Example: obama

text__icontains

Optional

number

The id for the meme
Example: 2

meme_id

Optional

number

Restricts query to memes that have at least N number of users
Example: 2000

num_users__gt

Optional

number

Restricts query to memes that have at least N number of tweets

num_tweets__gt

Optional

string

Restricts query to memes that have at least one event since the given time
Example: 2013-02-16T02:07:05

last_event_ts__gt

Optional

string

The type of the meme.
Example: hash_tag, mention, tweet_text, url

meme_type

Optional

number

The starting page for results to return. For example, specifying "offset=0" will bring back records 1-10, "offset="11" will bring records 11-20, etc.
Example: 0

offset

Optional

string

Orders by the given field. Add negative sign in front for descending order (-num_tweets_
Example: -num_tweets

order_by

Optional

HTTP 200 : Networks GET/networks
						{
  "id": 10,
  "network": "String Value",
  "text": "String Value"
}						
Networks

Meme communication networks in various formats (gexf, graphml, edgelist, adjlist). These are calculated daily from the past 90 days of Twitter communication. Not computed for memes with low activity levels.


Test console
Description
Parameter
string

The format of the network layout.
Example: graphml, gexf, edgelist, or adjlist

ext

Required

number

The unique identifier of the meme
Example: 2

meme_id

Optional

number

The starting page for results to return. For example, specifying "offset=0" will bring back records 1-10, "offset="11" will bring records 11-20, etc.
Example: 1

offset

Optional

HTTP 200 : string GET/timelines
Timelines

Data over time for particular memes


Test console
Description
Parameter
number

The starting page for results to return. For example, specifying "offset=0" will bring back records 1-10, "offset="11" will bring records 11-20, etc.
Example: 1

offset

Optional

number

The id of the meme
Example: 2

meme_id

Optional

HTTP 200 : Users GET/users
						[{
  "account_created": "String Value",
  "lang": "String Value",
  "meme_id": 10,
  "mentions": 10,
  "partisanship": 10,
  "resource_uri": "String Value",
  "retweets": 10,
  "sent": 10,
  "user_id": 10
}]						
Users

A user who has at least one tweet on the memes we track. We offer statistics about them such as political partisanship detection, sentiment analysis, and activity levels. All users are anonymous.


Test console
Description
Parameter
number

Restricts query to the users who have at least one tweet about a particular meme.
Example: 2

meme_id

Optional

number

The user with the id we are looking for
Example: 34231

user_id

Optional

string

The format of the request
Example: json, csv, xml

format

Optional

number

The starting page for results to return. For example, specifying "offset=0" will bring back records 1-10, "offset="11" will bring records 11-20, etc.
Example: 1

offset

Optional

string

Orders by the given field. Add negative sign in front for descending order (-retweets)
Example: -retweets

order_by

Optional

Consume this API completely for free!


By joining the mashape API marketplace you can start using Truthy API today!

Login to your account or signup: Create Account

or
   Signup with GitHub

By signing up you agree to our terms of service.