Styling markers

The marker-annotated (“pin-drop”) map is an easy to create visualization that can describe anything from your coffee shop checkin to the latest tropical storms. It has become commonplace on the web and with it data that is often a molten mess of content fused with presentational markup and inline styling. The simplestyle spec is a first attempt to clean up styles and data in a practical, light-handed way.

View the spec simplestyle-spec is an open specification on GitHub. Fork the repository and create issues or pull requests to improve the next version.

Eliminating literal styles

Some geodata formats have an established convention of including literal visual styles in their data. To show a magnitude 6 earthquake means entering <img src="earthquake-6.png" /> directly as a data value. Without a better, accessible solution on hand this has made datasets difficult to restyle or update. Worse, these files often contain data that can only be made usable through extensive parsing and data cleaning.

The goal of simplestyle is to preserve data cleanly while allowing a light layer of visual styling in several convention-based fields. Take for example an entry one might see for a marker in another geodata format:

<img src="earthquake-6.png" />
<strong style='color:#f44'>Virginia Earthquake 2011</strong>
<em>Magnitude 5.8</em>
No deaths, minor injuries. Damage to buildings reported.

In simplestyle GeoJSON, the entry properties would look like this:

"title": "Virginia Earthquake 2011 - Mag. 5.8",
"description": "No deaths, minor injuries. Damage to buildings reported.",
"magnitude": 5.8,
"marker-size": "medium",
"marker-color": "#f44"

By providing basic fields for content, marker styling fields, and allowing additional data keys to be added for important values, simplestyle would allow the same “pin-drop” data to be used to generate a custom visualization in TileMill, power a sorted list of earthquakes in browser, create markers in a native mobile app using the Mapbox iOS SDK, and more.

But I mean bus!

Simplestyle gives map makers three fields with which to visualize their markers:

  • marker-size: one of small, medium or large. Can be used to put greater or lesser emphasis on a marker based on its size.
  • marker-color: a valid RGB hex color, like #ff4444. Color can be used to put emphasis on markers, group markers together by various colors, associate markers with various color semantics (e.g. green means good, red means bad) and more.
  • marker-symbol: an icon ID from the Maki project or a single alphanumeric character (a-z or 0-9). Attach a specific symbolic meaning to a marker.

Each field allows map makers to attach a great deal of concrete meaning to each marker without venturing too far into literal visual stylization. Symbols are delegated to the Maki icon project which provides the default graphical implementation of each symbolic concept as well as the process of selecting a cartographically-relevant vocabulary. Yet these fields remain cleanly separated from the content and easily overridden or reinterpreted by implementers.

simplestyle in action

Any time you drop a pin on a Mapbox map you are creating GeoJSON that leverages the simplestyle spec. Your map has a markers API endpoint documented and maintained in our documentation

that can be dropped directly into L.mapbox.markers.icon() in Mapbox.js to add markers to your map.

Mission complete! Next up:

  • We’ve looked at how simplestyle offers a middle-of-the-road approach to marker styling - fields for concrete, visually compelling markers that are repurposable and cleanly separated from data. That same data can be used to create custom maps in TileMill. In the next section we’ll look at how Mapbox handles the daunting task of storing and transferring all those tiles that make up a custom map.