Highway shields in OSM-Americana

I’ve got a few questions about them.

How easy is it to drop them into another vector-based map style?

How easy is it to make shields sparser or plainer in a map style with a different aesthetic?

Is there a shortcut for adding road numbers in more countries?

Are there places where OSM-Americana is more complicated than it would otherwise have been because of how road numbers are mapped?

@ZeLonewolf :eyes:

Fantastic questions – you’re reminding me that we should finish writing OSM Americana’s FAQ.

We publish an NPM library for generating route shields that you can plug into any MapLibre GL JS map. It was originally designed for OpenMapTiles but can be configured for other tile schemas. Alternatively, you can fork the OSM Americana project, as the AARoads Wiki did for the locator maps in their articles.

Although MapLibre is a cross-platform software suite, Americana is written as a Web application, so some of the more advanced functionality like bilingual labeling and route shields aren’t as readily portable to native mobile and desktop platforms. That said, James Westman has done some fantastic work to port Americana’s features to GNOME Maps, which is written in C++ and isn’t even based on MapLibre Native. Regardless of the programming environment, Americana’s shield artwork is in SVG format, so it can be reused even in Mapnik-based raster styles.

A Mapbox GL or MapLibre GL style can set the symbol spacing for any layer, such as the layer that draws the shields.

You can configure the shield library to provide your own artwork or reuse Americana’s if it matches your style’s aesthetics. For a non-transportation-focused map, you can configure artwork that’s less ornate or conflates networks together with generic shields.

If you know of a country or region that doesn’t have shields on Americana but should, please open an issue about it and we can look into whether the necessary data is present and design a shield. If you’re interested in designing one yourself, we have a detailed contributor’s guide and are happy to walk you through the process.

As a style that prioritizes mapper feedback, we prefer to make things data-driven and shy away from nonobvious heuristics. If the data in OSM doesn’t support a particular cartographic need in a given country, we’re willing to forego the functionality until the tagging standards catch up. This differs from the approach taken by consumer-facing data consumers such as GNOME, Meta, and Mapbox.

In particular, Americana only renders shields along a route if it is mapped as a route relation with a network=* prefixed by the country code, plus ref=* and/or name=* as appropriate. We don’t support ref=* on ways, because that would require too much guessing and text processing heuristics that would take control away from mappers.

(The UK is an exception: the authorities there specifically assign and signpost road numbers as an analogue to road names, but they don’t number primary routes, which are orthogonal and poorly defined. A UK route shield is a combination of both the road number and the route classification. OpenMapTiles has compensated by synthesizing a “route” network based on highway=* classifications.)

Quite a few countries need improvement in terms of cleaning up network tagging or mapping the route relations in the first place. A common issue is that mappers have confused network=* with operator=* or is_in=*, calling everything national just because it’s operated by a national agency, or fragmenting the network with provincial namespaces even though the numbering is coordinated nationwide. We don’t attempt to recover from these issues. We’re slowly reaching out to individual mapping communities to inform them of the issue and collaborate on solutions. If you’re interested, this is one area where the project could use a lot of help, particularly from mappers abroad.

Aside from OSM data, most of Americana’s excess complexity actually comes from limitations in either OpenMapTiles or the MapLibre Style Specification. For example, some route networks color-code the routes, either in addition to or instead of the route numbers. Some networks have a consistent shield design that places a unique symbol in the middle instead of a number. Some place a veritable essay in the middle, but users would expect to see an initialism instead.


In the past, OSM Americana maintained a lookup table mapping refs or names to shields, but this was error-prone and difficult to maintain. Fortunately, OSM already tags the necessary information via keys like colour=*, ref:colour=*, and name=* on route relations, but we’re waiting for OpenMapTiles to expose these keys to the style.

Another source of complication is that network=* isn’t just about rendering shields. If it were, then the most common values would be rectangle and circle, or maybe a souped-up osmc:symbol=* syntax. Instead of these presentational values, we have semantic values so that geocoders can derive systematic route names and Americana’s own legend can associate each network with a label from Wikidata.

Unfortunately, that means many more specific values that a renderer otherwise wouldn’t need to care about. For example, the massive shield definition file maps over 500 distinct network=US:* values to the same basic blue and gold pentagon shape. OsmAnd has a similar table. But these values have to exist because routes in different counties aren’t necessarily related to each other in the real world, and the signs usually differ by a small line of text at the top that this style omits for simplicity.

Last year, @clay_c and I gave a talk about the efforts to internationalize Americana and how the community can help:

1 Like