Skip to content


Subversion checkout URL

You can clone with
Download ZIP


Pete Warden edited this page · 32 revisions


How to:

How to publish your Google spreadsheet on the web
How to use OpenHeatMap within your own site


What kind of locations does OpenHeatMap understand?
What options can you set on a map?
What do the upload errors and warnings mean?
Component API calls
Events list
International states and provinces example files

How can I map my list of addresses?

If you have a spreadsheet of street addresses, it’s best to lay them out like this to help the service understand them:

| Location                                    | Value |
| 2543 Graystone Place, Simi Valley, CA 93065 | 10    |
| 2098 17th St, San Francisco, CA 94114       | 20    |

The important parts are that you put the whole address in a single column (rather than breaking it into separate city, state, or street cells), give the column the title “Location” to help the service understand what it is, and add a “Value” title to control the color of the markers on the map.

What if I don’t have any values for my places?

You should create a dummy column filled with 1’s, and give it the header “Value”. This will make the service use the same color and size for all the markers. Here’s an example:

| Location        | Value |
| Los Angeles, CA | 1     |
| Boulder, CO     | 1     |

What if I just have ZIP codes?

If you have ZIP codes, use the column header “Location” like the examples above, and make sure you have a “Value” column too:

| Location | Value |
| 93065    | 10    |
| 94114    | 20    |

What if I have postal codes from outside the US?

Use the column header “Location” like the examples above, but add the country name at the end. Not all country’s post codes are supported, but generally the best form is to use something like , <country>, even if that's not the usual local form.

| Location                        | Value |
| South Australia 5343, Australia | 10    |
| South Australia 5345, Australia | 20    |

What does it mean if I see the error [Object][Object] when uploading?

It means that the server is having some technical issues that the administrator needs to sort out, unfortunately. These often happen with particularly heavy traffic, so it can be worth checking in later too. I hope to have a more permanent fix for these problems going forward.

What’s OpenHeatMap’s size limit for files?

There isn’t a hard size limit, but once you get beyond a few thousand rows, the files get slower to upload and render, and the chance of the server timing out increases. If you have a very large file with tens of thousands of lines, I recommend seeing if you can summarize the data to help the service digest it. For example, if you have a lot of addresses try using a pivot table in Excel to summarize them by ZIP code or state. If you have latitude, longitude coordinates, round them to the nearest 1/10th of a degree and then create a row for each grid cell instead of one for every individual point.

How can I get more flexibility in the maps I create?

OpenHeatMap is designed to be a simple, lightweight way of creating maps from spreadsheets, but if you’re looking for more power and don’t mind a bit more of a learning curve, I’m a big fan of the free QGIS desktop application.

Something went wrong with that request. Please try again.