Created: 2008-11-13 13:36
Updated: 2016-05-08 16:49
License: mit



TweetScope makes it easy to create themed single-page displays of twitter search results. (See these sites tracking #afterhours, #getoffmylawn, and CyborgCamp for example.)

Quick Setup

  1. Create a new site with rake site:create
  2. Edit your site's config.yml file (sites/sitename/config.yml) to set your site's title, tagline, query, and the number of results to display.
  3. Customize the appearance of your site by editing the css file (public/sitename/style.css) and the view template (sites/sitename/index.haml). The view template is written using haml.
  4. Test things out by running ruby tweetscope.rb and visiting http://localhost:4567 in your browser.


Global Configuration

The global_config.yml file holds application-level settings.

  • default_site: directory name of the default site to be served in a multi-site installation if no domain match is found. If this option is not set, TweetScope will display the first site alphabetically.
  • cache_max_age: cache expiry time, in seconds. No caching is performed by TweetScope itself, this simply sets the value of the Cache-Control header for use with an external caching system.

Site Configuration

Each site's config.yml file holds site-specific settings.

Query Settings

  • query: the query string passed to twitter search
  • language: restricts tweets to the given language, given by an ISO 639-1 code.
  • count: the number of tweets to return per page, up to a maximum of 100.
  • geocode: returns tweets by users located within a given radius of the given latitude/longitude, where the user's location is taken from their Twitter profile. The parameter value is specified by "latitide,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly.

Text Snippets

The default theme uses the config file to set the site title and tagline. Additional snippets of text can be added following the same key/value convention and accessed in the view template with @site['keyname'].

Site Settings

  • cache_max_age: the global cache expiration can be overridden on a site-by-site basis.
  • domain: a domain where this site is accessible (see Multiple Sites below).
  • domains: a collection of domains where this site is accessible (see Multiple Sites below).

Multiple Sites

A single instance of TweetScope can run many different sites. The domain (or subdomain) being requested is checked against all sites that have the domain or domains option set. If a match is found, that site is served.

When testing locally, sites can be accessed at http://localhost:4567/_sitename_


The current version of TweetScope is targeted for deployment on Heroku (it includes unpacked gems necessary for running there), but will play nicely with any Rack-compatible webserver. A guide to Heroku deployment can be found at

Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more