Frequently Asked Questions

For those who like to get right to it sample files that Dotspotting knows how to read are available here. If you make your files look like these, they should work fine.

The longer version, for those who like to read documentation:

What can I upload to Dotspotting?

You can import several different kinds of files—generally, lists of points and places. The common thing they need to share is some kind of geographic information that we can use to figure out where they are in the world. This will often, but not always, be a geolocatable street address, like: "2017 Mission St #300, San Francisco CA" or "350 5th Ave, New York, NY 10001". You can also use city names: "Miami FL" or "San Diego CA" will work fine. In some cases, for places with unique place names, you can even use just the name: Llanfairpwllgwyngyllgogerychwyrndrobwyll-llantysiliogogogoch (or Llanfairpwllgwyngyll for those in a hurry) works just fine, and there are more of these here.

The other way you can tell dotspotting where something is located in the world is by specifying its' latitude and longitude; basically how far from the equator and the Prime Meridian it is. There are several sites out there that will help convert an address to latitude and longitude; is one of our favorites. It will give you numbers like "37.7647463, -122.41951" when you search for "2017 Mission St SF CA" which is useful information if you're trying to put "Stamen Design, LLC" on a map.

It's important to remember that deriving point locations from text can be a tricky business, and that even Google gets it wrong some times (and they have alot more money than we do). So please be gentle! Rather than try and make this work for every data format under the sun, Dotspotting will take it's cues from our users, and we're providing some early examples of what works. If you've got a data format you'd like to see used, please go ahead and let us know.

Once you have this information, you'll need to put it into a file format that Dotspotting recognizes. Right now there are two kinds: Excel spreadsheets and .csv ("comma separated value") files. Each is outlined below.

Excel spreadsheets, with street addresses

Each item gets its own horizontal row, and each row has features that you assign to it. Typically you'd use "name" or "ID" as the title of a column, but you don't have to. You can also assign whatever other kind of feature you want: "color", "date_created", "my friend's name", "how long we dated" and "DNA reference code" are all valid titles. The important thing is that there's at least one column title that refers to geographic location in some way.

In the example below, a list of SRO hotels in San Francisco, the name of the hotel comes first ("title"), then the physical address ("Address"), then "created" (left blank here—maybe it refers to when the hotel was built? or when the record was created?), "type" (there are two types here: 'SRO' and 'SRO Human Services', presumably administered by different departments), and "location". In the absence of latitude and longitude information, "Address" is the only field dotspotting cares about. It will ignore "location", "type" and "title" for now, and it will do it's level best to parse the information in the "Address" field correctly.

Once you've got the data structured the way you like it, head over to the upload page, and go from there. Barring any errors, what you'll get out the other end should look like this:

Here's another example: a Department of Housing Preservation and Development list of the 100 worst housing violations in New York City, from a Curbed story and a housing dept survey:

In this case, the address is spread across four columns: "Borough" (NYC is the main US city that has these, but the states of Connecticut, New Jersey and Virginia also have them, sorta—did we mention this stuff was complicated?), "street_number", "street_name" and "city". Data structured in this way, even without "Borough," will also work.

Files that separate out addresses into several columns need have them labeled like this: street_number, street_name, city.

Uploading that file will get you a map that looks like this:

CSV and TXT files, with street addresses

CSV stands for "comma separated values," and it's another kind of file that Dotspotting understands. CSVs are similar to Excel files in that they've got rows, and those rows have data in them, and that data is labeled - but they're more like word docs in that you can easily work with them in text editors. They're also, by and large, smaller than Excel files, and you don't need Excel to read them. TXT files are just that: text files that you can edit in lots of different applications.

They look like this:

The first line is where column IDs are set:

address,description,contact info,comment

And the remaining lines are where the values for those columns go:

871 Sutter Street San Francisco CA,under construction

The order of the column headers is up to you. In this example address is the first column, but it could just as easily be the last. The important thing is for the rows to be consistent; you don't want to have "871 Sutter Street San Francisco CA" be the first item in one row and "under construction" be the first item in another row.

Latitude and Longitude

Some places don't have street addresses. Maybe you're tracking taxicab positions over time, or where sharks are in the ocean, or the flight paths of arctic terns. In these cases, you'll need to know the latitude and longitude of each dot.

Here's an example, from the USGS's Latest Earthquakes: Feeds & Data page:

Latitude and Longitude (highlighted in blue) are the fields that Dotspotting will look at first in this example. The values for those fields are highlighted in blue in the image below.

Because different sources of data are formatted differently, Dotspotting will read several different kinds of names for these data types. You can use (upper and lower case don't matter):

  • latitude, longitude
  • lat, long
  • lat, lon

Uploading this file will get you a map that looks like this:

For more on latitude and longitude, take a look here. There are some other examples of files using lat & lon (see?) available here.

Flickr and Google MyMaps import

Dotspotting will also import urls from Flickr and Google's MyMaps. The way to do make this work is to copy the URL from a particular set on Flickr or MyMap on Google Maps and paste it into the box under "Choose a URL to upload" on the upload page.

This should work with any public Flickr set, so long as the photos in it have latitudes and longitudes associated with them. It only works in sets for now. Most Google MyMaps pages should work as well; please let us know if you find an error.

Here are some Flickr sets that've already been uploaded, but which you can try out for yourself:

That's all for now

Go ahead and get started!

Source Code

Dotspotting is an open-source project licensed under the GNU Public License, version 3.0.

It is available for download on Github: