Getting Started with Blueshift
Quick Start
- 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).
- 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.
- 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
Geolocation
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.

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.

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.
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 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.
Similarly, you can use the radius property to visualize your data as points of varying size, sometimes called 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.
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.

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.