The Topsy API is a REST API served over HTTP. It is accessible via the URI:

All requests are implemented via HTTP GET or POST methods, with the exception of the Streaming API, which opens an HTTP connection.

All requests accept the API key via the apikey parameter. The URL for each request can be broken down into: resource name, response format, query parameters and API key string.

GET /resource.response-format?apikey=KEY&keys=values HTTP/1.1

Unless otherwise noted, the following output formats are supported: JSON (.json) and JSONP(.js). The exceptions are /content/bulktweets and /content/streaming which return a list of JSON objects, with each tweet being a JSON object, separated by a newline.

Resource documentation

Content APIs

These resources let you retrieve every single tweet or only the most relevant ones (e.g. newest or oldest tweets, tweets with the most reach) for any topic. You can also find content (links, photos and videos) shared on Twitter and all the tweets related to them, among other things.

  • Tweets – Top tweets for a set of terms and filters
  • Bulk Tweets – Tweets in bulk for a set of terms and filters
  • Streaming Tweets - Stream of tweets matching a set of terms and filters
  • Links – Top links for a set of terms and filters
  • Photos – Top photos for a set of terms and filters
  • Videos – Top videos for a set of terms and filters
  • Citations – Time-ordered tweets or retweets referencing a tweet, link, photo, or video
  • Conversation - Reply thread for a tweet
  • Tweet – Look up tweets by tweet ID
  • Validate – Check whether a tweet is still valid (has not been deleted by user) by tweet ID
  • Location – Set of places that start with a given string, to be used with /metrics/geo

Metrics APIs

Metrics are statistics derived from analyzing the full Twitter Firehose, available in real time (up to the minute) as data is being posted on Twitter, as well as going back to July 2010. Metrics are available in minute, hour, or day granularity.

  • Mentions – Number of tweet mentions by time slice for any term
  • Citations – Number of total citations (tweets, retweets, and replies) for a particular URL
  • Impressions – Number of potential impressions by time slice for any term
  • Sentiment – Topsy Sentiment Score (0-100) by time slice for any term
  • Geo Distribution – Number of mentions by country, state/province, county or city

Insights APIs

Topsy Insights APIs leverage full-Firehose analysis to surface key influencers, hashtags, and topics related to your topic of interest.

  • Related Terms – Phrases, hashtags, terms, or authors co-mentioned a given term
  • Influencers – Influential authors who talk about and amplify a given term
  • Author Info – Information about a Twitter account