FAQ

petewarden edited this page Sep 14, 2010 · 27 revisions

What is OpenHeatMap?
Who is responsible for it?
How is it related to OpenStreetMap?
Can I use one of these maps on my site?
Can I customize its behavior?
How is it licensed?
What technology does it use?
Why are you rendering on the client?
Why call it OpenHeatMap when it generates choropleths?
Why does the example need authorization for Twitter? You can download my followers without authorization.
How do I create an animated map?
How do the color key settings work?
How can I get OpenHeatMap working with Flashblock?

What is OpenHeatMap?

For users OpenHeatMap is a service designed to make it easy for non-specialists to create maps communicating information. It transforms data from a traditional data source such as a spreadsheet into an interactive animated view of a particular area. You can then share that map online, a bit like YouTube for geographic visualizations.

For developers, it’s a JQuery plugin that makes it easy to create a completely open-source mapping component on any web page, using either Flash or HTML5’s Canvas element under the hood depending on the platform and preferences.

Who is responsible for it?

It was started by Pete Warden in March 2010 as a personal project. You can contact him via pete@petewarden.com

How is it related to OpenStreetMap?

It was born from a drunken conversation with Steve Coast, and it reuses the OSM XML file format for its map data, and pulls in detailed background image tiles directly from the OSM site. It’s a separate effort because it has different goals and requirements. The most basic reason I can’t use OSM data as the basis for my maps is that they’re not closed polygons, they’re collections of lines. This is perfect for drawing road maps and other descriptions of the geography, but it doesn’t make it easy to fill large areas with color.

Can I use one of these maps on my site?

Sure! Here’s How to use OpenHeatmap within your own site. It’s a JQuery plugin, all completely open-source and available under the GPL, so you can explore the source code and examples to understand how to integrate it with your own data sources. In a nutshell, you’ll probably want to decide what area you want to display, and then create either a static or dynamically generated CSV file to produce the data. You may also need to add a crossdomain.xml file giving access to static.openheatmap.com if you use the flash component hosted here, though I recommend hosting everything on your own site.

Can I customize its behavior?

Everything but the core rendering is designed to be controlled by Javascript within the hosting page. You can get a list of the event hooks and callable functions at the Component API calls page

How is it licensed?

The code is all licensed under the Gnu Public License version 3, as is the US map data. The world map data is derived from http://thematicmapping.org/downloads/world_borders.php under a Creative Commons Attribution/Share Alike license.

What technology does it use?

The website backend and map processing tools are built using PHP. The overall control of the component is handled through Javascript, and there’s two alternative rendering engines; a Flash SWF file written in Flex and a pure Javascript implementation using Canvas on modern browsers.

Why are you rendering on the client?

I started with a client renderer because this makes it a lot easier to embed as a standalone component. It also places the computational burden on the user’s machine, which is good for my AWS bill but can cause problems on large data sets. It does make fast interaction and animation easier to implement however.

Why call it OpenHeatMap when it generates choropleths?

1 – It also generates the density/blob based traditional heatmaps if you supply it with data that resolves into latitude/longitude point positions rather than the names of areas like counties, zip codes or countries. Here’s an example showing Boulder real estate prices by neighborhood: http://openheatmap.com/view.html?map=LithophotogravureAndrogametophoreChurchianity

2 – It rhymes with OpenStreetMap

3 – I can never remember how to spell cloro… churo… that word

Why does the example need authorization for Twitter? You can download my followers without authorization.

It is possible to make API calls without authorization, but by default the limit is 150 per hour:
http://apiwiki.twitter.com/Rate-limiting

I can get IP addresses white-listed to bump that up to 20,000 per hour, but since I’m running a cluster of servers behind a load balancer, and the IP white-listing process can take several days, that isn’t very practical when I need to start up new servers on short notice.

How do I create an animated map?

If you name a column in your spreadsheet ‘time’, OpenHeatMap will use that to build an animation. For example:

This will create an animation containing two frames, 2008 and 2009, since those are the values in the time column. Every unique value in the time column will create a new frame, and will only display the values from the spreadsheet that are tagged with that time.

The time column can contain any string of characters, but will be arranged in dictionary order, so “August 2009” will actually appear before “July 2009”. To work around this, you should specify dates as “year number”-“month number”-“day number”, eg 2010-3-18. This will ensure that the frames appear in the correct order. I’m aware this is a bit clunky, and is high on my list to improve.

How do the color key settings work?

When you’re creating a map you can control both the colors used to display the values, and how each value is converted into a color. The first three color boxes let you control the start, middle and ending colors of the gradient.. For example if you set the start to white, the middle to grey and the end was black, you’d get a smooth gradient where low values in your data were drawn as white, and high values were drawn black, with mid-range values in various shades of gray. The fourth color box lets you control the color of the oceans and other background areas like the title.

The two numbers below the gradient boxes let you control which colors are chosen for values in the data. The first number is the starting threshold, and means that any lower values in the data get drawn as the first color in the gradient. For example, with a white-to-black gradient and a starting threshold of 10, rows with values less than 10 would all be drawn as white.

The second number is the ending threshold, and marks the upper limit above which all values will be drawn as the ending color of the gradient. With the same white-to-black gradient and an ending threshold of 20, all rows with values more than 20 would be drawn as black.

These starting and ending threshold define the range of values you can actually see in your map. Using the previous settings, all the rows with values between 10 and 20 would show up as different shades of gray. OpenHeatMap will choose a default range that most of your values will fall into, but if you want to highlight certain aspects of your data it can be helpful to edit these defaults. For example if you had unemployment data and wanted to focus on very high unemployment areas, you could set the starting threshold to 20 and the end to 40 to show the worst-hit locations.

How can I get OpenHeatMap working with Flashblock?

If you’re running on Safari or Chrome you can use the HTML5/Canvas version of the renderer instead of Flash, by appending ‘&prefer=canvas’ to the end of most of the URLs, or it will automatically fall back to Canvas if Flash is not installed. Unfortunately there’s a bug with Firefox when loading large XML files through JQuery that prevents a lot of maps rendering in HTML5 with Mozilla-based browsers.

If you want to whitelist just the domains that OpenHeatMap runs Flash from in your blocking add-in, you should be able to add openheatmap.com and static.openheatmap.com.s3.amazonaws.com