Fork me on GitHub

Using Torque Outside of CartoDB

Animation GIF

Talk at FOSS4G NA 2015

Kathryn Killebrew | Software Developer

Azavea Logo

What is Torque?

Torque is an open-source JavaScript library from CartoDB for

time series map visualization.


How are Torque Visualizations Created?

The simplest way to create a Torque time-lapse animation is to upload the data to a CartoDB account,

then select the Torque option from the visualization wizard. Here’s an example of L.A. rapid buses.

LA Metro GIF

CartoDB visualizations can also be embedded on other pages. The CartoDB Torque tutorial page contains an embedded Torque animation.

How is Torque JS designed to be used?

The Torque JavaScript library will let you create a Torque map layer that can be added to

a Leaflet or Google Maps base layer on your own web page.

The layer is defined with the user name of a CartoDB account to use, the name of the table to

visualize from the CartoDB account, and some special CartoCSS to define aspects of the animation.

Here’s an example from the Torque project

GitHub Pages. The source

is under the project’s examples directory.

Navy demo GIF

Can Torque be used without uploading the data to CartoDB?

A third option for using Torque, which we will explore today, is to use the library in conjunction

with two other CartoDB JavaScript libraries to connect to data that is not uploaded to a CartoDB

account, but is rather in our own PostGIS-enabled PostgreSQL database.

This presentation walks through setting up a stand-alone Torque animation.

CyclePhilly GIF

How Does Torque Work?

Torque is part of the suite of projects that make up the CartoDB web service.

It’s designed to work with the other projects, particularly the Windshaft tiler and SQL API service.

Torque queries the SQL API when initializing to get metadata about the table, such as the time

period covered and bounding box for the points, then fetches the animation from Windshaft.

The Torque animation is configured using special CartoCSS, defining aspects such as frame count,

animation duration, and the color and size of the markers used at different frame offsets.


Okay, How Does CartoDB Work?

CartoDB has several open-source components:

Um, Why Are You Doing This?

Lightbulb-Fixing GIF

Working on a volunteer project, CyclePhilly.

Already had a Windshaft server with PostGIS-enabled database displaying trips;

wanted to add Torque animations.

CyclePhilly Trips

So How Do I Use Torque Without the Other Stuff?

Torque only really needs the Windshaft tiler and SQL API CartoDB projects to work.

The Torque and Windshaft projects can be used without modification.

The SQL API will need to be set up to operate without user credentials from the CartoDB web app.

I’ll share a fork of the project I’ve configured to work as a stand-alone SQL API.

Note that redis is a dependency of both Windshaft and the SQL API; it’s used for caching.

The database is the one other component we’ll need.

How Do I Set Up the Database?

How Do I Set Up the Database Table?

Four columns are needed:

Setting up Windshaft

Setting up the SQL API

Once the SQL API is set up to operate without user credentials from Redis or user and database names

from the subdomain, we’re ready to go! Here’s a fork of the SQL API that has the authentication parts removed. For permissions, we can rely on using

a database role that has read-only access to just the table with our data for Torque.

The SQL API configuration files live in config/environments. Copy development.js.example to

development.js, and edit:

To run: node app.js from the project top-level directory.

Okay, cool! Show me some examples!


Also helpful

CartoDB Torque Demo Site

-torque-data-aggregation to cumulative.

(By default, previous values are discarded.)


Kathryn Killebrew


Animation GIF