Getting Started with Blueshift

Quick Start

  1. Upload the data you want to visualize. The data must be in CSV format. And at least one column must contain the names of geographic locations – countries, states, cities, or geographic coordinates (one latitude column and one longitude column).
  2. Geolocate the data. After uploading the data, you will be redirected to a page that displays it in table format. Press the orange “geolocate” button and follow the instructions to convert the location names listed in your dataset into geographic features that may be loaded onto a map.
  3. Visualize it in the map builder. The map builder page is linked in the navigation bar at the top. Once there, press the “add layer” button and select your dataset to begin mapping.
Quicker Start

If you don’t have any of your own data to visualize, you can go straight to step three. Open the map builder and play around with the world data that is already there by default.
Each of the above steps is elaborated in more detail below.

Data Upload

Uploaded data must be in CSV format (geojson format will also be supported soon). Column headers must be non-blank and must be in the first row. And at least one column must contain the names of geographic locations. Blueshift recognizes four different location types:

  • Countries*
  • States / Provinces
  • Counties (coming soon)
  • Cities
  • Point coordinates
* Countries are not necessarily the same as sovereign nations. For example, the geographic region associated with “The United States” includes only the 50 states plus Washington DC.  US territories, such as Puerto Rico and Guam, are each treated as distinct countries and must be geolocated separately.



After uploading your data, you will be redirected to a page displaying it in table format. Before it can be mapped, Blueshift needs to know what geographic features to associate with the location names in your data. Begin by pressing the orange Geolocate button, which will bring up this screen.

geolocate us cities

Provide some basic information about the locations listed in your data, and Blueshift will attempt to find the corresponding geodata

Since there are many world cities and states/provinces that share the same name (For example, Syracuse, NY / Syracuse, IN / Syracuse, Italy), you have the option of including additional information to make sure the geolocation finds the right one. When geolocating cities, you can specify the country and/or state where those cities are located (shown in the image above). Likewise, for states / provinces you can specify the country where those states / provinces are located.

The geolocation search is not case sensitive. And in general, it recognizes alternate names and abbreviations. For example, “USA”, “united states”, “the United States of America” will all be identified as the same place.

If the geolocator is unable to find any of your locations, they will appear in red at the top of the table once the geolocator has finished searching. You can then search for them manually by clicking on the red button and typing in the location name, as shown below.

geolocate us cities manual

Once the geolocator finishes its run, any items that are not found will appear in red at the top. You may then try searching for each of them manually.

Once you have at least one column fully geolocated, your dataset will be accessible via the map builder tool.


Map Builder

Once your data has been successfully geolocated, you can now visualize it on the map. Go to the Map Builder page, press the Add Layer button, and you will see it listed in the datasets. If you are working with countries or states/provinces, you have the option of displaying the locations as points or as polygons. If your locations are cities or geographic coordinates, you may plot them only as points.

When you load a new layer, the map will automatically zoom in to show just the regions you have added. For example, if you add the default “World” dataset as a layer, the map will show the entire world (if you have deleted the World dataset by mistake, download again as CSV). If instead your data includes just Canada, the US, and Mexico (download as CSV), the map will appear as below.

north america map

The map will scale and crop itself automatically, showing only the region included in your data

Styling layers: three different methods

The panel on the left side of the screen provides the options for styling the map. For each property shown (e.g. color, height, radius), you may style it in one of three ways.

  • Single value – all features are assigned the same value. For example, if you select the color grey in the left panel, all countries in the map will appear grey.
  • Data function (fixed) – each feature is assigned a different color, depending on its data. For example, you might color each country based on its population (e.g. big populations = dark colors, small populations = light colors).
  • Data function (animated) – each feature is assigned a different color, depending on data that changes over time. For example, if your data includes each country’s population for multiple years, you can visualize the populations as colors, showing how they have changed over time.
three map styling methods

Three different ways of coloring a layer: single value, data function (fixed), and data function (animated)

The example shown above uses color, but the principal works the same for other properties of the map. By varying the height, for example, you can create 3D maps like the one below. The heights in this one are fixed, showing the results of the 2016 election. With data from past presidential elections, you could make an animated version, with heights that change over time.

3d election map by county

Adjust the “height” property to make a map extrude in 3D

Similarly, you can use the radius property to visualize your data as points of varying size, sometimes called a bubble map.

mapping the great migration

Use the “radius” property to make a bubble map

By playing with the position property, you can visualize data, such as migration flows, as animated points, moving over time between locations. To see how this would work, have a look at this walkthrough showing how to build a map like this using international trade data.

international trade globe

The “position” property can be used to visualize your data as flowing particles

Map Settings

In addition to the option for styling specific layers, the settings panel in the bottom right corner also gives you various options for changing the look and feel of the map.

  • Base, Background: These settings control the color of the surface under the map and the color of the background space behind it.
  • Controls: This option determines what happens when the user drags with the mouse / swipes the screen. You can set the map either to pan (the default for flat maps) or rotate (the default for globes). Pressing the reset button will reset the control and the position of the map to its original state.
  • Projection: This setting determines what map projection is used in the display. If you’re unsure of what a map projection is, it should become obvious by playing with the different options (shown below). If you would like to get a better understanding of why you might choose one projection over another, here are a few of my thoughts.
map projections

There are six map projection options to choose from


To get started, go to your dashboard and upload a dataset. Or go straight to the map builder and play around with the world dataset that is already there.

You can also go through the process of creating a map from beginning to end by following along with this walkthrough.