Mapbox Studio Classic source quickstart

When you import geospatial data, Mapbox Studio Classic doesn’t apply visual styles to your files directly. Instead, Mapbox Studio Classic converts the raw data into Mapbox Vector Tiles. Studio’s source editor transforms traditional geodata formats into vector tiles containing the appropriate layers and configurations needed for styling.

In this guide, we’ll import a CSV file with earthquake data from the USGS and create vector tiles from the data. We’ll add the source as a layer and create a custom map style showing points for all the earthquakes that have occurred.

If you’re new to Mapbox Studio Classic, we recommend going through the Intro to CartoCSS and Studio and Mapbox Studio Classic style quickstart guides.

Getting started

For this guide, you’ll need:

Creating a source project

Open Mapbox Studio Classic and click on Styles & Sources in the lower left. Click New style or source to open the New style and source window.

New Project

From this menu, create a New source by clicking a Blank source.

Blank Source

Adding your first layer

To add a new layer. Click New layer and then Browse to find and select earthquakes.csv.

Add data

In the right panel, you’ll see the configuration view for your newly-added layer. The name of the layer will autofill with metadata from the file. You can edit the layer name by clicking the pencil icon. Leave it as earthquakes for now.

Verify that projection is set correctly. This field will also autofill with metadata from the file and it should reference WGS84. Mapbox Studio Classic autodetects the projection of most geodata files. If you have data that does not have its projection autodetected, report it as an issue on GitHub.

Set the Buffer size slider to 32. The vector tile buffer determines how much extra data is included around the edges of each tile and can be used to prevent visual clipping artifacts when styling data.

Click Done to see your new layer. Studio automatically assigns the layer a color and style in the data preview. You may need to zoom and pan a little to see your data in the preview.

Your layer settings should look like this:

Layer settings

Inspecting data properties

The map preview pane shows points and each point represents a distinct earthquake. Click on any point on the map to inspect the data for that earthquake. The layer name and color are shown so you can inspect multiple layers if features overlap. We’ll use these data fields later when styling this source.

Inspect layers

Adding field descriptions

Click the earthquakes layer. Then click on the Fields toggle to view all the fields present for this layer and descriptions of each field.

Fields

Enter descriptions for each field and then click Done. Field descriptions are a helpful guide to the contents of each property and how it might be used when styling. The USGS website includes a Glossary describing their data fields.

Setting the source's name and saving

Open the Settings panel on the far left. Here, you can set information about your project as a whole, such as a name, description, and attribution info for your data sources.

Change the name of the project to Earthquakes so when it’s uploaded you will be able to find it.

Settings pane

Click Save As to save your project locally. Mapbox Studio Classic source projects are saved as a directory of files with a suffix of .tm2source.

Uploading

Upload your project from the Settings pane by clicking Upload to Mapbox. Uploading a Mapbox Studio Classic source project to Mapbox.com will allow you to use the source for Mapbox Studio Classic style projects. Your uploaded source will appear on your Data page.

Upload source

Upload progress

Mapbox Studio Classic has converted your project to vector tiles and it can now be read from the Mapbox API. Once the upload is done processing Copy its map ID. You will use this to add your custom vector tiles to a custom map style.

Styling custom data

Next, let’s add style to our custom data. We’ll need to create a new style project to do that. Click on Styles & Sources in the lower left and then New style or source.

Select the Satellite Afternoon style to use a starting point for your new style.

New Style

Changing the vector tile source

Before we change our style’s source, click Save as to save your style project locally. Now that it’s saved, click on Layers to open the layers panel and then click Change source. Here, we’ll add our source’s map ID to this style project.

Change source

In the input field, add a comma at the map ID of your vector source to the end of the list of sources.

add map id

mapbox.satellite,mapbox.mapbox-terrain-v2,mapbox.mapbox-streets-v6,[map id here]

The Mapbox API will automatically composite the existing sources (Mapbox Satellite, Mapbox Terrain, Mapbox Streets) with your new source. Click Apply after you enter your source’s map ID.

Add a stylesheet tab

Click the + button on the top right of the style editor to add a new CartoCSS tab. Name your tab earthquakes. We’ll add all of the styles for the earthquake data here.

Add tab

Styling points

Let’s style each point where an earthquake has occurred. Add the following CartoCSS to your earthquakes stylesheet and then click Save to see your changes.

#earthquakes {
  marker-comp-op: screen;
  marker-allow-overlap: true;
  marker-line-width: 0;
  marker-fill: #a20;
  [zoom>=0] { marker-width: [mag] * [mag] * 0.1; }
  [zoom>=2] { marker-width: [mag] * [mag] * 0.2; }
  [zoom>=3] { marker-width: [mag] * [mag] * 0.4; }
  [zoom>=4] { marker-width: [mag] * [mag] * 0.6; }
  [zoom>=5] { marker-width: [mag] * [mag] * 1; }
  [zoom>=6] { marker-width: [mag] * [mag] * 2; }
  [zoom>=7] { marker-width: [mag] * [mag] * 4; }
  [zoom>=8] { marker-width: [mag] * [mag] * 8; }
  [zoom>=9] { marker-width: [mag] * [mag] * 12; }
  [zoom>=10] { marker-width: [mag] * [mag] * 24; }
  [zoom>=11] { marker-width: [mag] * [mag] * 48; }
}

The code above does the following:

  • marker-width: [mag]*[mag]*n properties draw each earthquake point as a circle scaled by its [mag] field.
  • [zoom>=n] selectors increase the size of each circle as you zoom in.
  • marker-allow-overlap: true allows the circles to be drawn over each other.
  • marker-comp-op: screen switches the blend mode of the markers so overlapping circles create an interesting visual affect.

Your map should now look like this:

Styling points

Styling labels

Next let’s add labels so that the earthquakes with a large magnitude are labeled clearly on the map. Add the following CartoCSS to your earthquakes stylesheet and then click Save.

#earthquakes::label[zoom>=6][mag>=4],
#earthquakes::label[zoom>=8][mag>=3] {
  text-allow-overlap: true;
  text-size: 14;
  text-name: '[mag]';
  text-face-name: 'Open Sans Regular';
  text-fill: #fff;
}

The code above does the following:

  • #earthquakes::label defines a new label CartoCSS attachment. The properties in this attachment will be drawn on top of any previous #earthquake layer rules.
  • text-allow-overlap: true allows text to be drawn on top of markers and other labels.
  • text-name: '[mag]' sets the layer field to use for the contents of the text labels.

Your map should now have labels for the large magnitude earthquake points:

Styling labels

Uploading

Upload your project from the Settings panel by clicking Upload to Mapbox. You can change your style’s settings from this panel at anytime, but you’ll need to upload again to reflect changes.

Upload style

Mission complete

Your map style is now deployed Mapbox on your Styles page and has a map ID. You can use this map with any of the Mapbox developer APIs to integrate into your apps and sites.

To learn more about sources in Mapbox Studio Classic, check out:

Next article:

Mapbox Studio Classic style quickstart

With CartoCSS you can add buildings, parks, and roads to the Mapbox Basic style. In this guide, we'll do just that and add tooltips to the POI layer.

Additional questions? Ask our support team or learn more about How Mapbox Works.