Minh Nguyen's Diary

Recent diary entries

Updating names in Texas

Posted by Minh Nguyen on 14 June 2021 in English (English). Last updated on 23 June 2021.

Last week, the U.S. federal government finally agreed to retire a number of racially insensitive names of landforms and bodies of water in Texas, 30 years after the state legislature petitioned the federal government to rename them after accomplished Black Texans. (Most of them had originally been named with an even worse racial slur.) OpenStreetMap has been updated to reflect the new names that are in GNIS, the federal government’s official gazetteer. The corresponding Wikidata items have also been added or updated, to prevent data consumers from overriding OSM names with the offensive old names, but also to link to more information in Wikidata and Wikipedia about the person whom the feature now commemorates.

Most of the features had to be mapped for the first time, because GNIS doesn’t have enough detail about linear features like valleys and creeks to import them, and NHD had only been imported in a few parts of the state. Except for Emancipation Pond, which is in a residential development under construction, a traveler is unlikely to ever stumble upon these remote features in the vast Texas landscape. Even so, much more accessible locations get renamed practically every day. Hopefully these OSM and Wikidata entries will serve as a handy model for mappers to follow as we find more efficient ways to track and respond to name changes.

Updated name OSM feature Wikidata feature Wikidata namesake
Freedom Hollow Added Added
Hendrick Arnold Bluff Renamed Renamed Added
Buffalo Soldier Creek Added Added
Bill Pickett Hill Renamed Renamed
Jack Johnson Creek Added Added
Lake Henry Doyle Added Added Added
Lake William Goyens Renamed Added Added
Matthew Hooks Reservoir Renamed Added Expanded
John Horse Hollow Added Added Expanded
George Ruby Bend Added Added Expanded
Norris Cuney Gully Added Added Expanded
Negros Liberty Settlement (abandoned) Removed
Leonard Harmon Hollow Added Added
Ada Simond Creek Added Added Expanded
Milton Holland Creek Added Added Expanded
Emancipation Pond1 Added Renamed
Kiamata Creek Added Added Added
Henry Flipper Hill Renamed Renamed Expanded
Negro Tank (demolished) Removed
Buffalo Soldier Draw2 Added Renamed

Position statement for 2021 OpenStreetMap U.S. board election

Posted by Minh Nguyen on 25 January 2021 in English (English). Last updated on 30 January 2021.

I’m running for reelection to the OpenStreetMap U.S. board of directors.

For those who don’t know me, I’ve been contributing to the OpenStreetMap project as a volunteer since April 2008, mostly as a mapper and an advocate for the project. I love pondering tagging dilemmas and seeding the map with a level of detail that pleasantly surprises users and gets them off the sidelines. (As for my day job, I’m proud that the iOS software I write at Mapbox is powered by OSM data, but I’m my own board member and mapper.)

In my position statement last year, I wrote about the need to build bridges. Since then, OSMUS and the OSMF achieved normalized relations via a local chapter agreement. Without the distraction of local chapter negotiations, we can look forward to partnering with OSMF in forging less obvious relationships that bring more participants into the OSM project.

I had looked forward to meeting many of you at this year’s State of the Map U.S. conference in Tucson. Instead, we responded to the upheaval of 2020 by organizing the Connect conference and continuing a series of Virtual Mappy Hours that ranged from imports to issues of social justice – all at a safe distance online. I hope you found these events to be as worthwhile (and as much of an escape) as I did.

As a board member, I arguably had the least hands-on role in each of these team efforts. My job has been to connect them to the bigger long-term picture. It’s important for me to give our executive director, Maggie, the room to get the implementation details right but also be available for a gut check or proofread as needed.

In 2021, that bigger long-term picture becomes more concrete. Charter programs and our collaborations with non-profits, the public sector, and corporations are evolving OSMUS beyond an organization that merely organizes events. As we give these efforts a chance to blossom, we must also prioritize the health of the existing community. There are still many hurdles keeping people from getting more deeply involved in OSM’s decisionmaking and organizing. As a board member, I would support and advise Maggie in discovering and addressing these barriers.

I encourage you to read the other candidates’ position statements, hear more from us at the upcoming town hall on Wednesday, and cast your vote by February 7th. In addition to voting for the board, please remember the part about the proposed change to the bylaws. Thank you for your consideration!

capk11, CC BY-SA)

Location: Farmington Hills, Oakland County, Michigan, United States

Help us add businesses in Silicon Valley

Posted by Minh Nguyen on 7 December 2020 in English (English). Last updated on 18 April 2021.

Here in San José, we’ve begun importing tens of thousands of businesses from an official registry of South Bay businesses and other points of interest that are open during the COVID-19 pandemic. When we’re done, our POI coverage will look similar to this visualization:

POIs in Santa Clara County POIs in Downtown San José

We want you to be a part of the import effort! Go to this MapRoulette project and follow the instructions to get started. It’s a safely socially distanced activity and a small way to help the local community come out stronger after the pandemic (not just the local tech industry).

If you’ve never participated in an import before, this is a good opportunity to learn, because you can use the same editor your normally use. (For me, that’s iD.) Each challenge corresponds to a different business category, so you can pick the kind of POI you’re most comfortable mapping.

Example MapRoulette task

You don’t need to live in the Bay Area to participate. In fact, even mappers outside the U.S. have an interest in comprehensive POI coverage here in Silicon Valley. For better or worse, OSM’s reputation is partly based on its reputation among tech companies. Everyone evaluates a map service by searching and navigating while running errands, and tech company decisionmakers are no exception. If OSM can deliver a good experience in Silicon Valley, we’ll have more opportunities to serve people elsewhere, including in places where OSM is already a hidden gem. This import will also serve as a model for other cities to supplement their POI coverage with similar data sources.

If you have any questions or would like help getting started, please feel free to send me a message or invite yourself to OSMUS Slack’s #local-california channel. Thank you!

Location: Downtown Historic District, San Jose, Santa Clara County, California, 95113, United States

A limited time weight reduction offer

Posted by Minh Nguyen on 3 October 2020 in English (English). Last updated on 31 December 2020.

The other day, while adding some Ohio county roads to route relations, I came across a baffling weight limit sign:

Lilly Chapel–Georgesville Road looking north from London–Lockbourne Road

As complicated as it can be, OpenStreetMap’s maxweight tagging is designed around explicit numeric values. What good is a 10% discount when you don’t know the full price?

A state bridge inspection manual pointed out that this sign was once standardized as sign R12-H7 in the Ohio Manual of Uniform Traffic Control Devices (OMUTCD), but the sign was removed from the standard in 1997 in favor of explicitly posting the specific weight restrictions by axle count. (Old signs like this often remain until they wear out and the local highway department needs to replace them.)

At the same time, I discovered that a similar percentage-based sign has remained in the standard, now renumbered as R12-H17. Counties and townships are allowed to post it on roads and bridges to protect them during thawing season. (Other northern states have similar provisions.)


After a few days of research, I managed to come up with a machine-readable representation of R12-H17. The sign implicitly refers to a complex section of the state legal code that defines the legal truck configurations and weight limits associated with each configuration. I tried to distill that down into the usual conditional tagging syntax. It’s a mouthful compared to what’s literally on the sign:

maxweight:conditional=12 st @ (Feb 1-May 15)
maxweight:hgv:conditional=12 st @ (Feb 1-May 15 AND axles=2); 36800 lbs @ (Feb 1-May 15 AND axles=3); 43200 lbs @ (Feb 1-May 15 AND axles=4); 49600 lbs @ (Feb 1-May 15 AND axles=5); 55600 lbs @ (Feb 1-May 15 AND axles=6); 31 st @ (Feb 1-May 15 AND axles>=7)
maxweight:hgv_articulated:conditional=32 st @ (Feb 1-May 15)

As far as I can tell, there are currently eight legal truck configurations in Ohio: 2F1, 3F1, 4F1/SU4, SU5, SU6, SU7, and 5C1. The SU* configurations are for special hauling vehicles (SHVs), also known as single unit vehicles, for example cement trucks and garbage trucks. The single unit configurations appear to be uniform throughout the country, but the others may vary by state.

Unreduced weight limits by configuration
ConfigurationAxlesArticulatedUnreduced legal limit
2F12No15 short tons (14 t)
3F1323 short tons (21 t)
4F1427 short tons (24 t)
SU5531 short tons (28 t)
SU6634¾ short tons (31.5 t)
SU7738¾ short tons (35.2 t)
5C15Yes40 short tons (36 t)

The configurations are primarily known by the number of axles, and secondarily by whether the truck is a single unit (including a special hauling vehicle with closely spaced axle groups) or a truck-trailer combination. The general-purpose weight limit sign, R12-H5, identifies the configurations by these two aspects. However, the regulations are very particular about the spacing between any two axles and how much weight is applied to each axle. In some configurations, the axles are unevenly spaced and have different weights applied to them. For both signs, I ignored everything except for the axle count and unit count. I’m assuming that any truck configuration that’s illegal in the State of Ohio would be out of scope for the maxweight key anyways.


I alternated between expressing some limits in short tons and others in pounds. In Ohio, the authorities use pounds and kips in regulations and manuals, but they only post tonnages on signage. (Compare to Texas, which only uses pounds on signage.) I only used pounds for some cases because the percentage reduction would’ve resulted in a fractional limit and ambiguity about rounding and significant digits.

Given that the weight limit reduction sign is relative to unsignposted state laws, the actual values will change the next time the law changes. This is unfortunate but, in my opinion, an acceptable tradeoff for keeping data consumers from having to navigate the complexity of legal load limits that vary by state. The relevant state law was last updated in 1993, though the SHV configurations were introduced more recently, around 2016. I don’t expect the laws to change frequently. But just in case, I’ve also been mapping traffic_signs and also adding ad-hoc tags like maxweight:relative=-10% and maxweight:start_date=1989-09-12, which will make it easier to find these roadways to update.

This effort was only for a single standard sign design in Ohio, but hopefully the reasoning here will help others as they try to make sense of regulations and signage in other U.S. jurisdictions.

Photo courtesy of jbthemilker, hero of Ohio’s armchair mappers, and licensed under CC BY-SA 4.0.

Location: Fairfield Township, Madison County, Ohio, United States

Position statement for February 2020 OpenStreetMap U.S. board election

Posted by Minh Nguyen on 27 January 2020 in English (English). Last updated on 5 February 2020.

I’m running for reelection to the OpenStreetMap U.S. board. I’ve been contributing to the OpenStreetMap project as a volunteer since April 2008, mostly as a mapper and an advocate for the project. (My day job, writing iOS software at Mapbox, also intersects with OSM to some extent.) Last April, you elected me to the board to fill Maggie Cawley’s seat after she became our executive director. Thank you for taking a chance on me – I’d be humbled to continue to serve the community in this capacity.

I like to think I left things a little better than I found them. By the time I began nine months ago, board meeting minutes hadn’t been published publicly for over two years. As secretary, I’ve published minutes of each monthly meeting as soon as the board approves them at the following meeting. It may be some of the least exciting stuff I’ve ever written for the Internet, but published minutes are an important way for the OSMUS organization to stay in touch with its members. In conjunction with the monthly newsletters that I can’t take credit for, you know what’s on our radar and – just as importantly – can find out if something isn’t. Whoever wins this election, I hope the board will keep up the momentum. (If you have any feedback about the contents of these minutes or know of something else the board should take up, please let us know.)

Robert’s Rules aside, I could tell you about my work to train new mappers, improve documentation, advise on tagging proposals, and moderate thorny disputes, each of which have picked up to some extent over the past year. But the truth is that none of these activities strictly requires a seat on the board. What a seat on the board affords is a platform to steer the organization and use it to promote a vision for the broader project.

My ongoing priorities for OSMUS, which I outlined in my previous position statement, can be summed up as building=yes bridge=yes. (Building bridges, get it?)

Last year, I had the privilege of attending and speaking at State of the Map in Heidelberg. People warned me that I was going to hear an earful from people who didn’t have much good to say about the U.S. community. In fact, more than anything, the folks I met were curious about the Americans and wanted us to be better integrated into the global project. To the extent that there are unresolved issues preventing, say, OSMUS from becoming a local chapter, they seem finally solvable and the right discussions with the right people will get us there. The U.S. community as a whole already has an outsized, if soft-spoken, role in OSM, but reducing friction and increasing cooperation between the local and global communities will enable U.S.-based individuals and corporations, mappers and developers, users and advocates to participate more fully in the project.

Building bridges is important because we have a lot of room for improvement. Our meetups don’t reflect the diversity of the country we map. We constantly have to explain why our project matters when people find the competition so convenient. Our map contains a lot of cruft, and the processes and resources needed to clean it up aren’t always readily available. There are technical approaches to each of these problems, but they can only go so far unless we also step outside our comfort zones and connect with more people. As a board member, I would support and advise the executive director in engaging with community organizations, corporations, and program sponsors.

Our project’s ambitions are broad but at times difficult to articulate. For one thing, we can improve by being more than a traditional map and embracing unconventional methods. Whatever our tactics for advancing the project, it’s critical to keep our eyes on the big picture, as if we have nothing to lose.

I encourage you to read the other candidates’ position statements, hear more from us at two town halls, and cast your vote by February 9th. Thank you for your consideration!

capk11, CC BY-SA)

Location: Farmington Hills, Oakland County, Michigan, United States

Local color

Posted by Minh Nguyen on 25 January 2020 in English (English). Last updated on 27 January 2020.

(This post is cross-posted from a recent post on my blog and adapted for an audience already familiar with OpenStreetMap.)

A year ago, I was pretty sure I’d be spending all my free time mapping buildings and turn lanes. I did contribute plenty of them, but I also have a tendency to get distracted by ideas out of left field. During the past year, I wound up focusing on several kinds of features that never make it onto conventional maps. At some point, I took up mapping flags.

A taboo

The first atlas I owned as a kid was The Picture Atlas of the World (Kemp & Delf). The beautifully illustrated maps and infographics endeared this volume to me for years, but it was the colorful ring of national flags around the front cover that made it irresistible to me at the bookstore. It’s a wonder that my parents gave in to my pleas and purchased this atlas, despite the “red flag” of the Socialist Republic of Vietnam gracing the cover. My grandparents fled the Communists in the ’50s, and they with my parents fled the Communists again in the ’70s. Like many refugees, they longed for Vietnam – especially after searching in vain for Vietnamese food – but hearing about life there today, good or bad, would often elicit dismissive eye-rolling about the Communists.

The Picture Atlas of the World The flag of the Socialist Republic of Vietnam appears on the cover of this children’s illustrated atlas. (© Dorling Kindersley, used for critical commentary)

That was in a suburb of Cincinnati where Vietnamese are few and unknown. It was a bit easier for them to put the war behind them when no one around them seemed to know or care about Vietnam. But that wasn’t the case everywhere. Whenever we visited a Little Saigon in another city, I was fascinated by all the steps they had taken to maintain civic continuity with the old country: the major streets renamed “Sài Gòn” and “Trần Hưng Đạo”, the veterans marching in ARVN fatigues on holidays, the South Vietnamese flag raised proudly beside the American flag.

Wilcrest The City of Houston has renamed the major thoroughfares in its Little Saigon, posting Vietnamese signs of equal prominence as the older, more pronounceable English signs. Here, Wilcrest Drive has been renamed in honor of the unnamed soldiers of the Republic of Vietnam Military Forces (Chiến Sĩ Vô Danh VNCH). OpenStreetMap is the only online map that indicates the Vietnamese name, which is increasingly important for navigation as the English sign fades. (© Mapillary, CC BY-SA)

Later I’d learn that activists have convinced numerous city councils and state legislatures to give the South Vietnamese flag official status, regardless of international diplomacy, usually under a name like “Heritage and Freedom Flag”. The “yellow flag” is so important to these communities that, once in awhile, some official or business owner will unwittingly spark outrage, protests, and apologies by flying the wrong flag to represent the local Vietnamese American population.

Người Việt The South Vietnamese flag flies at equal height with the American and California flags outside the offices of Người Việt, a Vietnamese-language newspaper. (© Codobai, CC BY-SA)

Name that flag

About six years ago, I noticed an approved scheme for mapping flagpoles and the flags that fly on them. According to the scheme, flags are classified as “national”, “regional”, “religious”, etc., and national flags are identified by ISO 3166 country code. It was specific enough to precisely describe most of the flags in my hometown, so I didn’t think much more of these tags after mapping a few American and state flags. I had more important things to contribute to OSM anyways, like redrawing roads that the Census Bureau had turned into abstract art.

Vietnam War Memorial in Houston The Vietnam War Memorial in Houston’s International District took over the middle of a shopping center parking lot. This being Texas, the flags are large enough to easily identify in aerial imagery. (© WhisperToMe, public domain)

But then I started mapping Little Saigons. Nothing marks these communities as indelibly as the South Vietnamese flag. It’s the first thing to map, more important than the buildings and businesses. Yet no one has ever compiled a comprehensive listing of the places where the South Vietnamese flag flies. For that matter, no one has ever made a comprehensive map of these flags. That makes OSM the perfect place to start one.

Unfortunately, when I started mapping South Vietnamese flags, the approved flag tags were too imprecise to identify it, because folks hadn’t considered that a flag could outlast its country. As it turns out, South Vietnam’s ISO country code was VN, but after the war, the ISO obsoleted North Vietnam’s VD and repurposed VN to represent the reunified Vietnam – one of the spoils of war, apparently. I couldn’t simply tag these flags as flag:type=national and country=VN, as the OSM Wiki suggested, without fearing that an OSM-powered map would automatically depict them as Communist flags in the heart of a fervently anticommunist community. Indeed, OSM2World would color the South Vietnamese flag red based on the ISO country code, though it is possible to override the color explicitly.

Vietnamese flag at United Nations Headquarters As far as I know so far, the only flag of Vietnam that flies outdoors in the U.S. on a permanent basis is the one outside the U.N. headquarters in New York. (© Kriss Omana, CC BY-SA)

A quick search in taginfo showed me that someone had coined a more freeform flag:name key in 2014 and used it ad-hoc on a few flags without documenting the key on the wiki or campaigning to get it approved. flag:name=South Vietnam was an improvement in that I could make sure other mappers know which flag it is. But there was little chance that a future flag-bearing map renderer would special-case specific values of this key, given the sheer number of flag designs and the fact that the name could differ based on the local language where the flag flies. I needed to pair flag:name with another key set to an external identifier, which a renderer could use to look up machine-readable details in an external database.

I knew of two projects attempting to comprehensively catalog flag designs: Flags of the World and Wikidata. Both contain entries for the flag of South Vietnam, but I figured I’d eventually map other flags that weren’t in either database. My previous e-mail submissions to Flags of the World went nowhere, whereas anyone can create new Wikidata items while mapping. Moreover, Flags of the World lacks strictly unique identifiers: each webpage does have a somewhat memorable URL slug, but multiple flags can be documented on the same webpage. By contrast, Wikidata is organized around unique item identifiers (also called QIDs). It also has an API that makes it easy for software to reliably look up details, such as the flag’s aspect ratio, a scalable image to render, or even the Flags of the World URL slug if necessary.

Usage history of flag:name and flag:wikidata The Ohsome analysis tool shows flag:name was introduced in 2014 but went virtually unused until last year. flag:wikidata was introduced last year as well, and both keys have rapidly increased in usage. (© HeiGIT, map data © OpenStreetMap contributors, ODbL)

flag:wikidata follows the example of several other common keys that are set to QIDs, so I could use this key a bunch of times and expect other mappers and renderer developers to intuit the meaning behind it. But just in case, I informally suggested this new key on the man_made=flagpole tag’s talk page and eventually documented both flag:name and flag:wikidata on their own wiki pages to raise awareness.

Praying for a gentle breeze

Now I needed to get more flags on the map, to prove out the idea of tagging specific designs. I turned my attention back to my hometown and its mundane collection of American and state flags. Actually, I had missed plenty of other flags that needed QIDs for disambiguation: the five flags of the U.S. Armed Forces turned up at veterans’ memorials and outside the homes of many veterans. Some Catholic churches and cemeteries fly the local archdiocesan flag. McDonald’s restaurants fly a familiar Golden Arches flag. The high school I attended celebrates its Barcelonan exchange students with a Catalan flag – but my parents preferred to think of it as the similar-looking South Vietnamese flag.

St. Xavier High School Stadium St. Xavier High School in Cincinnati flies the flags of rival athletic teams, the three states where its students live, and the countries that send exchange students. Catalonia’s flag flies under the Spanish flag because of the school’s longstanding partnership with a school in Barcelona. (© Eugene Kim, CC BY)

Probably the main reason no one had ever rigorously catalogued individual South Vietnamese flags is that, important as each one may be to a particular community, it isn’t famous enough that word of that individual flag would usually spread across the country. Armchair mapping offers a way around that, since anyone can comfortably identify flags in street-level imagery and sometimes even aerial imagery. It took me only a few minutes to find South Vietnamese flags in the most well-known Little Saigon, in Garden Grove, California. But apart from that, it’s still time-consuming to think of Vietnamese shopping districts and scour imagery for a little yellow speck to zoom in on. Not nearly every Vietnamese grocery store would fly the South Vietnamese flag, just as not nearly every mainstream grocery store flies the American flag out front.

As a shortcut, I figured that places of worship catering to Vietnamese Americans would be just as likely to fly flags out front as mainstream places of worship, but much more likely to fly the South Vietnamese flag alongside the American flag. OSM has a lot of places of worship in the U.S., thanks to an import of the federal government’s official gazetteer, GNIS. GNIS is by no means comprehensive when it comes to places of worship, and it brought in lots of long-gone churches. Fortunately, it also has a tendency to call Vietnamese places of worship by descriptive names like “Vietnamese Alliance Church” rather than the actual, diacritic-laden names like “Hội Thánh Tin Lành Việt Nam”. So simply searching for “Vietnamese, United States” turned up quite a few churches, many of which do fly the South Vietnamese flag. I made sure to rename these churches according to signs I spotted in street-level imagery, and in some cases I had to move the church quite a distance from where GNIS had it, so there was a practical benefit in addition to the symbolism of getting flags on the map.

Vietnamese Alliance Church of Midway City GNIS had this church as “Vietnamese Alliance Church”, but despite subsequent mass bot edits, it had never been tagged as belonging to the Christian and Missionary Alliance denomination. It also hadn’t been tagged with its equally prominent Vietnamese name, though many Protestant churches use the same Vietnamese name anyways. (© Märker Geospatial, CC BY-SA)

I turned up more Catholic churches by searching for the names that Vietnamese Catholics most commonly venerate, but in English: “Vietnamese Martyrs”, “Our Lady of Lavang”, “Andrew Dung Lac”. Aside from flags, these search results gave me a chance to micromap other details like outdoor Stations of the Cross. Similarly, I mapped a lot of statues after searching for Vietnamese words that commonly appear in the names of Buddhist temples, like “Phat” (Phật) and “Quang”.

Vietnamese Martyrs Catholic Church in Arlington, Texas The American, Holy See, and South Vietnamese flags fly outside Vietnamese Martyrs Catholic Church in Arlington, Texas. An outdoor Stations of the Cross is just out of view to the right. By sheer luck, this intersection sports a tornado siren – another hidden map feature I’ve been focusing on. (© Kevin Ewing, CC BY-SA)

I was pleasantly surprised to have access to street-level imagery in most of the localities where I found places of worship to map. That made it much easier to map unfurled flags. Sometimes, though, I had to resort to process of elimination. For example, sometimes the street-level imagery was taken at a time of day when the flags were down, but there was enough of a breeze to unfurl the flags in aerial imagery. From a set of three flags outside a Catholic church, I could often deduce that the one with a dark canton was the American flag, the yellow one was the South Vietnamese flag, and the yellow and white one was the flag of the Holy See. I made sure to tag any other flag I saw along the way, creating a corresponding Wikidata item if necessary.

Ultimately, thanks in large part to Nominatim, I managed to map more than 45 South Vietnamese yellow flags across the U.S. and Canada, making it one of the most commonly tagged flag designs in OSM. (I did spot a couple red flags too, but notably none in the U.S. other than the one outside the U.N. headquarters in New York.) flag:wikidata is now one of the most commonly used Wikidata-related keys in OSM, more common than artist:wikidata and architect:wikidata, identifying Pride flags, Confederate flags, and everything in between.

South Vietnamese flags in OpenStreetMap (Run the query) It’s no surprise that Houston and Orange County in Southern California are so bedecked with yellow flags, given the very large Vietnamese populations in both areas. But they show up in some unexpected places too, like Greer, South Carolina, and Sundre, Alberta. OSM doesn’t record the stories behind these flags, but it could serve as a starting point for research. (© OpenStreetMap contributors, CC BY-SA; map data © OpenStreetMap contributors, ODbL)

I look forward to OSM’s coverage of flags increasing dramatically as others find out about this project and scour their own communities for flags. For now, only specialized 3D renderers show flags at all. overpass turbo let us see the invisible flag data, but it requires some training, such as in a walkthrough I gave at State of the Map U.S. last year. As flag coverage increases, I hope renderer developers will take note and add more sophisticated support for this data.

Raising the bar

I’m not mapping South Vietnamese flags in order to bear witness against Communism or to reopen old wounds. Rather, I want to ensure that Vietnamese American communities are represented on the map where they are today, in a way that’s meaningful to them. They already know where to find phở and bánh mì; what matters more is awareness and recognition. I want OSM’s attention to detail to bring people into the project from a broader range of backgrounds. The OSM community needs more diversity – not only among mappers and developers, but also among users and advocates – to establish the project’s relevance in society and keep it sustainable over the long term.

We need to expand our ideas of what OSM can excel at. Flag data is superfluous – until it represents new knowledge about the world that has never been expressed before or leads to improvements to the surrounding map. If we allow OSM to be judged solely by how well we provide the kind of information that people expect out of proprietary maps, OSM’s legacy will at best be a later, less efficient, less integrated Google Maps, merely a more current, detailed imitation of the paper maps in my collection. To be sure, roads, buildings, and businesses are an important baseline for a layperson’s trust in a map, but a baseline alone doesn’t capture people’s imaginations and spur them to action. Let OSM’s corporate infantry figure out how the project can compete with proprietary data sets on baseline data, while we grassroots mappers focus on mapping something quirkier, something more colorful that gets the next generation hooked on maps.

You can help

To map a flagpole in iD, add a Point and search the feature types for flagpole in the sidebar. The built-in fields so far only let you indicate the flag’s type (flag:type) and ISO country code (country), but you can add the flag:name and flag:wikidata keys manually in the “All tags” section at the bottom of the sidebar. The wiki’s flagpole documentation explains some of the nuances, like the difference between governmental and organisation, and how to find or create a QID in Wikidata. But don’t stop there: think creatively about what else might be important to a community’s identity and find ways to represent that on the map too.

Location: Little Saigon, San Jose, Santa Clara County, California, 95116-2246, United States

Your friendly neighborhood event calendar

Posted by Minh Nguyen on 1 July 2019 in English (English).

If you’re organizing an OpenStreetMap-related event, consider adding it to the wiki’s global OSM event calendar, which also appears in each issue of weeklyOSM. Even if you don’t expect to attract new attendees via the event calendar, it’s a decent way to raise awareness of your local community within the broader OSM community.

To add an event to the calendar, go to the Main Page and click the little blue ✏️ link at the top of the calendar. Follow the instructions on the edit page and click “Save changes”. Note that editing the calendar requires a free wiki account with a confirmed e-mail address. Otherwise it’d be too easy for spam to get in.

(If you’re organizing a regularly recurring event for a local community, you should also advertise it in the community index that appears after uploading a changeset in iD.)

Same great taste with half the punctuation

The event calendar has been rewritten to make it easier for non-programmers to contribute new events. In the past, adding an event to the wiki’s event calendar meant editing delicate HTML microformats and idiosyncratic templates. But more realistically, it meant copy-pasting an existing event and hoping for the best. Now a single template handles the implementation details for you, so you can focus on the details that matter.


| {{Cal|pizza}} || {{Dm|y=2019|Feb 7}} || <span class="p-name">[// Civic Hack Night & Map Night], [[San José, California|San José]], [[California]], [[United States]]</span> {{SmallFlag|USA}} {{SmallFlag|California}}


| type = pizza
| date = 2019-07-11
| name = Civic Hack Night & Map Night
| url = //
| city = San José
| citylink = San José, California
| region = California
| country = United States

On the surface, it’s just a small change – but hopefully one less thing to stress out about as you organize the event. As a bonus, the calendar takes significantly less time to load compared to the old implementation, which makes a big difference when viewing the Main Page.

Under the hood, getting to this point required writing a new template that retained full compatibility with weeklyOSM’s calendar parser, which had been optimized for the old syntax. It was also an opportunity to eliminate options that unnecessarily complicated the code or editing experience, such as unused support for event coordinates and Dzongkha date formatting. (Also, the German city shields are gone. 😬)

Looking ahead, there are more ideas on the table for making it easier to manage the calendar. Further improvements to the wiki’s page load performance are also in the works.

Thanks to everyone who provided feedback and reported bugs as the new template was being developed. If you run into any difficulties contributing to the calendar, please provide feedback on the calendar’s talk page.

Location: Longfellow, Minneapolis, Hennepin County, Minnesota, 55406, United States

Position statement for spring 2019 OpenStreetMap U.S. board election

Posted by Minh Nguyen on 1 April 2019 in English (English).

I’m running in the upcoming election to fill an open seat on the OpenStreetMap U.S. board. I’ve been contributing to the OpenStreetMap project as a volunteer since April 2008, mostly by armchair mapping, shoe-leather mapping, and fiddling with the wiki, where I recently became an administrator. I’ve also done a bit of importing and as much evangelization as the folks around me will bear. (My day job, writing iOS software at Mapbox, also intersects with OSM to some extent.)

OSM has the potential to be profoundly more than a tech project. When we see someone lavishly micromapping their neighborhood, we can rejoice that we’ve given them and their community a voice, that OSM has broken new ground, that we’re chipping away at an ancient, one-size-fits-all, top-down approach to mapping the world. We’re incredibly lucky that many people have discovered our project and figured out how to contribute. Just imagine how many more people will discover us once we figure out how to speak to their interests.

As a board member for 2019, I’d like to work with other board members and the newly appointed executive director to:

  • Stay in touch with OSMUS members. The recent town hall and virtual mappy hour felt like long-awaited reunions. I’m glad for that, but we should hold more of these meetings and get more people to show up beyond the mailing list and Slack regulars.
  • Develop resources to help community members plan and execute imports of public-sector data. Besides navigating the import process, mappers need help identifying datasets and approaching data owners with confidence. Lowering these barriers can help ensure that what we end up importing is the best data available.
  • Promote the use of OSMUS server resources for tools that benefit U.S. mappers and outreach efforts. What would a U.S.-centric renderer look like? What tools would be more useful in your day-to-day mapping if we had U.S.-specific versions of them?
  • Forge closer relationships with other free-culture and civic groups, including Wikimedia and Code for America. These communities already have the kind of distributed infrastructure that we imagine when we talk about OSMUS doing local outreach. Local wiki and civic hacking groups are already aware of OSM but may not be aware of the ways OSM can complement their message and power their projects.

This is the first time I’ve run for a leadership position in the OSM community. I’m jumping into this election knowing that I have a lot to learn, but hopefully also some unique perspective to share with OSMUS at this special time in the organization’s history.

We’re lucky that we have too many well-qualified candidates to choose from for this one open seat. 😄 I encourage you to read all of our position statements and cast your vote by Sunday, April 7. See you on the other side!

Location: Farmington Hills, Oakland County, Michigan, United States


Posted by Minh Nguyen on 2 January 2019 in English (English).

Oldenburg is a small town in southeastern Indiana, not far from where I grew up, where German is in some respects the official language. The town is proud of its German heritage. If you rely on a proprietary map for directions from Batesville to Metamora, you’ll probably miss a right turn at Oldenburg, which posts street names in German and only begrudgingly in English.

I don’t speak a lick of German, but when I found out that most of Oldenburg is included in a federally designated historic district, the town promised to be a good time sink. What better way to poke at a moat than to make a detailed 3D map of this Old World town, replete with German street names?

OSM versus Google Maps versus Apple Maps

To be included in the National Register of Historic Places, a building needs to be described in a publicly accessible nomination form. In the case of Oldenburg, that means nearly every freestanding structure in town, plus a patch or two of sidewalk, is given a full historical and architectural treatment. The document includes building names (typically after the original owner), floor counts, roof shapes, construction materials, and plenty of details we don’t have established tags for yet.

(Like many NRHP submissions, the one for Oldenburg is in the public domain because it was first published before 1989 without a copyright notice or registration.)

There’s still some work left to do: at least one 3D renderer, F4 Map, randomizes attributes like building heights and tree leaf type when you leave those details out, and there are still a few streets whose German names I couldn’t ascertain (while trying to avoid copying out of Google Street View). Hopefully this post will inspire a mapper in Cincinnati, Indianapolis, or Louisville to make a pilgrimage to this former monastery town for some proper field surveying.

There are thousands of historic districts on the NRHP all across the U.S., and not all of them require translation into English. What other historically significant places await your micromapping skills?

(Photo of Oldenburg skyline © 2016 Chris Flook, CC BY-SA)

Location: Oldenburg Historic District, Oldenburg, Franklin County, Indiana, United States


Posted by Minh Nguyen on 9 April 2018 in English (English).

This OpenStreetMap account celebrated its tenth birthday yesterday. (Happy birthday, OSM Account!)

Over the last decade, contributing to OSM has:

  1. helped me cope with homesickness
  2. given me too many good reasons to procrastinate on schoolwork
  3. led me to old friends
  4. led me to new friends
  5. taken my inner roadgeek to a new level
  6. taught me more about geography and GIS than I’d ever learn from a book
  7. made me a worse driver (but a better notetaker)
  8. helped me land a job
  9. given my open source contributions a purpose beyond attribution
  10. kept me from forgetting where I come from

Thank you, OSM community, for welcoming my contributions in the first place and for making my stay here as rewarding and meaningful as it has been. Here’s to countless more changesets, mailing list posts, wiki edits, and pull requests!

A cow made of corn

Posted by Minh Nguyen on 20 September 2017 in English (English).

It’s corn maze season in North America: for a couple months, farms all over are inviting folks to explore mazes they’ve cut out of corn fields.

CVNP A corn maze in Northeast Ohio by David Fulmer, CC BY 2.0.

In OpenStreetMap, several corn mazes have been micromapped across Southwest Ohio. The designs change each fall, so the mazes have to be micromapped all over again.

Wendel Farms pumpkins Look sideways: these pumpkins at Wendel Farms were previously visible in Bing and other aerial imagery, but the ways clearly need to be deleted now that the pumpkin design has been cut down (and replaced).

None of the aerial imagery providers have this fall’s maze designs yet – after all, these doodles are only weeks old in some cases. So I turned to the farms’ websites and Facebook pages, where farmers have posted aerial photos of their own mazes. I wrote to them, briefly describing OpenStreetMap and asking permission to update the map based on their photos. A few got back to me, happily giving permission. It’s free publicity for them, after all.

Wendel Farms cow This year, Wendel Farms’s corn maze depicts a cow surrounded by various dairy products.

Since my preferred editor, iD, currently lacks support for overlaying arbitrary images, I built a copy locally and modified it to display the photo above the normal imagery and below the data. Using my browser’s Web inspector, I added a pattern to the SVG document’s <defs> element:

<pattern patternUnits="userSpaceOnUse" id="maze" width="956" height="1174">
    <image x="0" width="956" height="1174" href="dist/img/pattern/maze.jpg" y="200" />

and overrode the CSS style of the <path> element representing the edges of the field:

.area-fill > .w107158117 {
    fill: url("#maze") !important;

I probably could’ve done something more sophisticated to keep the image anchored while panning and zooming, but this was good enough for a quick, informal micromapping project.

Wendel Farms cow

Not too long from now, these corn mazes will’ve been cut down and plowed under, and the paths will also be deleted from OpenStreetMap in anticipation of next year’s corn maze season. But a snapshot of this fall’s designs will eventually appear in the standard aerial imagery and remain there for years to come. As a result, mappers can compare a corn maze’s appearance and the date on which the maze was micromapped to determine the vintage of the surrounding area’s imagery.

In the meantime, if you poke around Southwest Ohio, be on the lookout for cows and other scenes hidden among the cornstalks.

Location: Reily Township, Butler County, Ohio, United States

Finding Wilson Boulevard

Posted by Minh Nguyen on 22 May 2017 in English (English).

(This post is cross-posted from a recent post on my blog and adapted for an audience already familiar with OpenStreetMap.)

An overflowing bánh mì, a tray of tender bánh da lợn, a can of soybean milk: my treat after every monthly trip to the little Vietnamese grocery across town. Mekong Market was my Sunday Bible school of Vietnamese culture in a childhood as distant from Asia as one could imagine, in Cincinnati. Snacks, sauces, and canned foods defying translation lined the shelves; in the refrigerator, a variety of mystery meats wrapped in aluminum foil each bore the same place of origin: Chicago.

One Labor Day, my family made a trip up to Chicago to finally see the bustling Vietnamese community whose clearance we had happily bought for years. We made a lot of road trips back then, often just spur-of-the-moment driving through the peaceful countryside. But since we were headed five hours away to an unfamiliar city, we needed to plan ahead. As the resident map enthusiast, I was to find directions to the Vietnamese supermarket in Chicago using our new Internet connection. We’d enjoy some phở for lunch and bring back enough fresh ingredients to avoid Mekong Market for a little while.

A search for “Vietnamese markets in Chicago” on AltaVista turned up an article from The Washingtonian describing a cluster of supermarkets, phở restaurants, and bakeries on Wilson Boulevard. I pasted the street address into MapQuest, specified “Chicago” and “Illinois” to make sure I got the right “Wilson”, and printed out the directions.

Bánh mì thịt nguội
A Vietnamese cold cuts sandwich (bánh mì thịt nguội).

Five hours later, we arrived in Chicago and crawled up and down Wilson Avenue. If a Vietnamese supermarket or two were to be found along this street, it couldn’t have fit very easily inside any of the modest townhouses that lined the street from end to end without interruption. I noticed, too, that the entire length of the street was numbered in the 8000 range, as opposed to the 6700 block on which this supermarket supposedly stood. My father pulled the car aside and called the supermarket’s phone number on his cell phone. I could understand just enough Vietnamese to make out the voice on the other end: “I’m in Northern Virginia – what in the world do you want me to do for you?”

As my father held his tongue – Grandma was in the back seat – we wandered aimlessly around that part of town until we happened to spot some Vietnamese signage. There, just a few minutes away from Wilson Avenue, were the supermarket, phở restaurant, and bakery we had been hoping for, by sheer luck.

In the years since, I moved to San José, California, home to one of the largest populations of Vietnamese Americans in the country. Bánh mì shops here are as commonplace as cafés. In fact, the only reason I ever notice them is that I also became immersed in OSM. I found a niche mapping “flyover country” and made it my mission to improve coverage of communities underserved by commercial map vendors, among them ethnic enclaves in San José, Orange County, and elsewhere.

Last month, I happened to be in Washington, D.C., visiting my employer Mapbox at the new office there. On a lark, I decided to spend Sunday afternoon visiting Wilson Boulevard for real. It had been almost eighteen years since my last attempt, but despite having since moved to a city with a large Vietnamese population and plenty of Vietnamese food, I figured seeing this street in person would give me some closure. Fortunately, the same Metro line that took me almost to the airport also took me almost to Eden Center, the Vietnamese shopping center that had teased me back in grade school.

Parking aisles
No Vietnamese shopping center would be complete without a kitschy gate.

I had always imagined Eden Center to be more of a bazaar than a strip mall. Nonetheless, it has almost everything you’d expect from a center of Vietnamese social life: a dearth of parking, a man singing karaoke to an impromptu crowd out front, a father treating his daughters to the kumquats that hang from a decorative tree nearby. On the other hand, there are no elderly men playing cờ tướng in front of the shops, as one often finds in California. (One wall bears an enormous warning against gambling and suggests area casinos as alternatives.)

Like similar centers in Orange County, Eden Center is steeped in war history. Each aisle in the parking lot bears the name of a South Vietnamese general.

Parking aisles
At the intersection of Nguyễn Khoa Nam and Trần Văn Bá “Avenues”.

The South Vietnamese flag flies proudly beside the American flag. As it was the week before the anniversary of the Fall of Saigon, a banner spanning the two flagpoles honored South Vietnamese war heroes.

South Vietnamese heroes banner
The banner reads, “With Gratitude We Revere the Martyred National Heroes of the Republic of Vietnam”.

I thoroughly field-surveyed Eden Center, noting the restaurants, jewelers, beauty salons, travel agencies, and karaoke bars tucked away in the center’s “mini-malls”. Before leaving, I bought a bánh mì, a piping hot tray of bánh da lợn, and a can of soybean milk for the road.

The whole reason I got involved with “citizen mapping” is that proprietary map sources fall so short when it comes to places beyond San Francisco, beyond the central business districts, beyond the tourist traps.

Eden Center on Apple Maps
Apple Maps includes only a few shops, but they’re all in the wrong places and some are no longer open.

Eden Center on Google Maps
With the same indoor mapping style it applies to every mall, Google Maps makes it look like it has spectacular coverage of Eden Center. But it’s just walls: most of the shops are still in the wrong location and some have closed.

Eden Center on Baidu Maps
I found it surprising that Baidu Maps has coverage of this area on par with Apple Maps, but it too has misplaced and outdated points of interest.

OSM didn’t have a lot of detail about Eden Center until I ventured there last month, but now it’s complete, accurate, and up-to-date. Even the parking aisles are named. It’s looking a lot better than the competition.

Eden Center on OSM, before and after
After my visit to Eden Center, OSM gained so much detail in the area that there isn’t enough room to display most of the points of interest with proper icons and labels. (Left: before; right: after)

Eden mini-malls on OSM, before and after
(Top: before; bottom: after)

Eden Mini Mall on OSM, full detail
One of the advantages of a human-curated map database is an at-times quirky attention to detail. The abundance of diacritical marks in Vietnamese are essential to comprehension, so this Vietnamese-American community will find it helpful that OSM includes the diacritics, even though this shopping center is located in a predominantly English-speaking city. Maybe someday the highway=corridor ways will be useful for pedestrian routing, too.

OSM may have a long way to go before it can even dream of breaking people’s Google habits. I’m under no illusions about how poorly it scales to visit each site in person via public transportation. But for now, I’m just happy to have finally made it to Wilson Boulevard and made it easier for others to do the same – minus the detour.

Location: Falls Church, Arlington, Virginia, United States

Highway shields, state by state

Posted by Minh Nguyen on 25 July 2016 in English (English). Last updated on 3 October 2020.

With State of the Map U.S. still fresh on everyone’s mind, let’s revisit a favorite topic among many U.S. mappers: highway shields. We’ve been talking about ways to improve the sorry state of route shield support across the OSM ecosystem since at least 2011. We haven’t yet reached the vision outlined by Richard Weait in that SotM talk, but things aren’t as bleak as the renderers may let on.

In America, things are complicated

The national standard for U.S. state route markers is black numerals in a white oval. But almost every state eschews this oval in favor of its own design. (Some states have several, depending on the type of road.)

State highway shields by state (Chris-T)

In most states, the marker consists of a number in a distinctive shape, possibly with color:

Kansas state highways, such as K-10, are indicated on signage by a yellow sunflower, the state’s official flower. (Steve Alpert)

By adopting these various designs, maps can optimize usability for motorists. While driving, one should be able to compare the route shield the navigation application is displaying with guide signage up ahead, without having to know the ins and outs of the local road network. Getting the iconography correct is important because the same route number on a different shape may lead you in a different direction.

SR 562
Ohio state highways, such as SR 562, are indicated by the state’s simplified shape. (allen, CC BY-SA 4.0)

Regular expressions to the rescue?

Unlike most OSM-based maps, the recently departed MapQuest Open layer included different route shield designs for each state. But it relied on a fragile assumption that the way’s ref tag had to begin with the state’s postal abbreviation, e.g. ref=KS 10 in the example above. Parsing a way’s ref tag is suboptimal for various reasons:

  • There are known conflicts with other countries and other countries’ political subdivisions. For example, ref=CA… occurs in both California and the Cantabria region in Spain. ref=NH… occurs both in New Hampshire and throughout India.
  • Some states have multiple statewide route networks. Texas famously uses 12 distinct shield designs for state-level routes, and several of these networks overlap numerically. The postal abbreviation isn’t enough to distinguish one network from another.
  • Many states have county, township, or even city routes with distinct markers. In Ohio, each county has its own design, and within many of those counties, there are a variety of township route marker designs. A generic prefix like CR or TR is insufficient for selecting a suitable marker image, yet fully qualifying the jurisdiction on every way (ref=US:OH:MRW:SouthBloomfield 190) would also be tedious and error-prone.

In some states, the highway department doesn’t use the state’s postal abbreviation when abbreviating route numbers, nor do most residents in writing:

Ohio uses “SR” on variable message boards where a pictograph would be infeasible. (ODOT)

In Ohio, the consensus has been to tag ways with the “SR” prefix and rely on route relations for disambiguation. Some other states have similar practices. Unfortunately, this approach caused the state’s routes to be marked with the generic oval instead of the state’s shape. MapQuest Open is no longer available on, but the need to choose state-specific shields remains common among renderers.

For years, members of the U.S. OSM community have promoted an alternative, more flexible tagging scheme for highway routes: the ref and network tags on route relations. In 2013, Phil Gold developed an experimental “shield renderer” to demonstrate how a renderer might make use of this data:

The OSMUS shield renderer supports a variety of shield designs as well as route concurrencies.

But making use of route relations is a difficult problem for production-level consumers of OSM data, so parsing ways’ ref tags remains the most common approach to selecting route shields, despite the disadvantages above.

“Perl Problems”, xkcd (Randall Munroe)

A baby step using spatial queries

When I’m not mapping speed bumps and backyard swimming pools for fun, I work at Mapbox on the open-source Mapbox iOS SDK and the Mapbox GL renderer that powers it. Mapbox GL renders Mapbox Streets vector tiles, applying a stylesheet designed in Mapbox Studio.

The style language used by these tools doesn’t yet support regular expressions, so the vector tiles can’t include the raw way refs for the renderer to parse. Instead, when an OSM way is baked into a vector tile, a spatial query determines the relevant ISO 3166-2 code (the country code plus the postal abbreviation), which goes into an iso_3166_2 field.

This field makes it possible for anyone to create a map that includes state-specific route shields. To prove it, I used Studio to create a custom style, Interstate, based on the default Streets style:

With a regular expression–based filter, a conventional renderer would be unable to distinguish between Ohio and Indiana state route refs.

I wanted to get back to armchair mapping, so I only customized the shields for Ohio, Kentucky, and Indiana rather crudely. But with a bit of effort and more graphics design chops than I possess, the other states could receive similar treatment.

Note that this is only a stopgap solution to the problem of choosing state-specific shields: Mapbox GL doesn’t support grouped icons for route concurrencies yet, and ISO 3166-2 codes don’t identify counties, townships, or the myriad route networks in Texas. But it’s still better than seeing homogeneous white ovals everywhere.

Build your own Interstate

It takes a certain amount of roadgeekery to care about state-specific route shields on a map, but it doesn’t take any programming skills to design and publish a style like Interstate:

  1. Sign up for a free Mapbox account and open Studio.
  2. Click New Style and choose a template. (Other than Satellite and Empty, each of the templates is based on the Mapbox Streets source and thus OSM data.) For this style, I chose the Streets template: Templates
  3. Zoom the map in to level 10 or beyond and center it somewhere in the U.S., so that the generic oval state route shields are visible.
  4. The left sidebar lists the style’s layers, which are akin to layers in a vector graphics tool like Inkscape or Adobe Illustrator. Expand the “Highway shields” folder. Layers
  5. Two layers of interest are “road-shields-white” and “road-shields-black”. The former is for shields that have white text, such as for Interstate highways and California state highways, while the latter is for shields that have black text, including most states’ highway shields. For this style, select “road-shields-black”. (You can also click on the roads on the map to select these layers.)
  6. In the flyout for this layer, switch to the Icon tab and note that the Image property is set to {shield}-{reflen}. Mapbox GL fills in the shield and reflen tokens so that a three-digit state route gets the us-state-3 shield. Now switch to the “Select data” tab. The lengthy filter ensures that the layer doesn’t rope in any roads whose shields should have white text. The map highlights the ways that remain. These are the state routes you want to style. The filters beforehand Data on the map
  7. At the top of the layer list, click the Duplicate button and name the new layer “road-shields-state-black”. Duplicate
  8. In the new layer’s “Select data” tab, delete the existing shield filter. Replace it with one that includes a shield that “is any of” us-state. Then add another filter for an iso_3166_2 that “is any of” US-OH, US-KY, or US-IN. The resulting filters
  9. Back in the Style tab, in the Icon tab, change {shield}-{reflen} to {shield}-{reflen}-{iso_3166_2}. You’ll be adding icons with names like us-state-3-US-OH. (Alternatively, you could create a separate layer for each state, but more layers means more maintenance overhead and possibly worse performance.)
  10. Uh-oh: where previously there were generic state route shields on the map, now there are only numbers. Missing shields Click the “{}” button on this text field to open the icon manager flyout. The style already has a lot of icons, including highway shields for many countries. Icon manager flyout Click the “Add SVG Images” button and upload a roughly 20×20 SVG image for each state-reflen combination you want to support. If you’re looking for inspiration, here are some existing SVG route shield sets that you could adapt in Inkscape or Adobe Illustrator (MUTCD-compliant iconography is in the public domain, but note that some designs may be trademarked): * Shield templates from the 2013 shield renderer – Remove the text span from each image before use. Mapbox GL will superimpose the route number onto the shield. You can customize the number’s styling in Studio. * Shield blanks from Wikimedia Commons – You may want to remove the black background from many of these images. The black background improves visibility for reassurance markers, but it’s unnecessary when the shield is merely a “sticker” on a map. * Some crude images I made based on a few of the Wikimedia Commons images above
  11. After uploading the images, you should see them in the flyout, and the map should now show state-specific shields. Uploaded icons Shields fixed Finally, click the Publish button at the top of the left sidebar to make your changes public.

As seen on TV

I encourage you to check out Interstate. The map starts out at the Ohio-Kentucky-Indiana tripoint, so you can see the special style rules in action. Unlike the 2013 shield renderer, Interstate is the real deal: it’s served from production servers, ready to be embedded in a Web, desktop, or mobile application. (But please create your own copy using the instructions above instead of hotlinking this demonstration style.)

An example of what an iOS navigation application would look like using the Interstate style, the Mapbox iOS SDK, and the OSRM-powered Mapbox Directions API.

It’s worth noting that the ref tag isn’t just for renderers: OSRM includes the ref of each way along the route, so that a turn-by-turn navigation application can announce “Turn left onto SR 4.” If locals don’t refer to the highway as “OH 4”, neither should the voice announcement.

The ISO 3166-2 codes exposed by Mapbox Streets partly decouple the ref tag’s format from the visual output. This frees up the ref tag to reflect the notation that’s used by humans and verifiable “on the ground”, rather than some arbitrary standard enforced for the benefit of renderers. The sooner we wean renderers off their dependence on specific ref tag patterns, the sooner we can expect renderers to support route relations. I can’t wait for that day to arrive.

The map is a fractal

Posted by Minh Nguyen on 24 July 2016 in English (English).

I spent this morning watching live online transcripts of State of the Map U.S. roll in. (What a time to be alive!) Each year, there’s a talk or lightning talk that looks to the future. Alan McConchie’s talk today imagines the project’s possible trajectories, both good and bad. The eventual outcome may end up being some combination of Alan’s scenarios: a ghost town in some respects, a garden in other respects, a Borgesian map in Germany even.

In most of my eight years armchair-mapping for OpenStreetMap, I’ve stayed pretty close to where I started: in my hometown of Cincinnati, Ohio, in the United States. At some point, especially after moving across the country to Silicon Valley, I must’ve imagined that I’d eventually map Cincinnati to completion and move on to other, less well-tended areas. But that never happened. Instead, I found myself mapping the same places over and over again, even as my interests expanded to neighboring counties and states.

To me, OpenStreetMap behaves like a fractal: the beautiful structure in mathematics that gets more intricate the longer you stare at it.

Koch snowflake
Koch snowflake, António Miguel de Campos, public domain

Iteration 0

Koch snowflake iteration 0
Koch snowflake iteration 0, Wrtlprnft, public domain

The zeroth iteration, back in 2008, was tracing Yahoo! Aerial Imagery in Potlatch 1. Despite having tons of free time back then, the best I could do with the tools I had was:

  • Realigning TIGER-imported roads to Yahoo!’s blurry imagery
  • Dividing TIGER-imported freeways into dual carriageways, reclassifying them above highway=residential, and adding them to relations
  • Removing “(historical)” GNIS-imported schools and post offices or retagging them as historical=yes
  • Adding misshapen buildings (because Potlatch didn’t have a right-angle tool) that looked OK at z17
  • Tracing river centerlines
  • Delineating golf courses and cemeteries

Iteration 1

Koch snowflake iteration 1
Koch snowflake iteration 1, Wrtlprnft, public domain

When the first iteration began sometime in 2010, allowing me to trace Bing aerial imagery in Potlatch 2, any area I mapped had to meet a higher standard. But I also couldn’t help but go back and retrofit the old areas – areas I cared about most – to meet this higher standard too:

  • Realigning hand-drawn buildings to have right angles and look OK at z18
  • Adding cul-de-sacs and crosswalks
  • Adding soccer fields and tennis courts
  • Tracing riverbanks and wooded creeks
  • Tracing the paths in golf courses and cemeteries
  • Expanding the network of high-voltage power lines
  • Aligning county boundaries to better follow road and river centerlines

Iteration 2

Koch snowflake iteration 2
Koch snowflake iteration 2, Wrtlprnft, public domain

Roughly each year since then, Bing and Mapbox have provided ever sharper imagery for the area, and that imagery has revealed just how much the world changes on a regular basis. Again I had to retrofit my original areas of interest:

  • Adding traffic lights and alleys
  • Adding new wings to industrial buildings as they expand
  • Deleting houses as they’re torn down in urban renewal programs
  • Replacing farmland with residential subdivisions
  • Delineating and naming residential and retail developments
  • Aligning city limits to changes in road pavement quality

Meanwhile, the community grew alongside the map. People with very different interests than me built up bicycle infrastructure, identified countless coffee shops, filled in the map’s background with land use polygons, and even cleaned up the buildings I’d previously drawn.

Iteration 3

Koch snowflake iteration 3
Koch snowflake iteration 3, Wrtlprnft, public domain

These days, newer tools like iD and Mapillary mean so much more source material to map and so many more tempting presets to make use of:

  • Realigning hand-drawn buildings to look OK at z19 and counting their floors
  • Naming businesses that never would’ve caught my attention while field surveying
  • Entering lane counts, speed limits, and turn restrictions
  • Adding sidewalks, crosswalks, and driveways
  • Adding backyard swimming pools
  • Tracing drainage ditches

Bots, crowdsourcing tools like MapRoulette, and paid mappers are present, too, taking care of basic upkeep so fractal mappers like me can focus on the next level of detail.

The next iterations

Koch snowflake iteration 7
Koch snowflake iteration 7, Wrtlprnft, public domain

Today at State of the Map U.S., there’s talk of mapping curbs and verges, of tracing “road banks” the way we started tracing riverbanks in iteration 1, of using 3D building data in ways that’ll probably require ever granular measurements. Machine learning is taking the gruntwork out of armchair mapping, freeing us to map even more creatively.

Each time I embark on a new iteration of the fractal, I get much the same overwhelming feeling that I got when I first opened Potlatch 1 back in 2008. It’s like we’re starting from scratch, filling in data we didn’t expect to ever care about, except the tools are right here to support us.

Whatever the future appearance of OpenStreetMap and its community, the full potential is, fittingly, a version of the coastline paradox. Unlike Borges’ map, OpenStreetMap’s fractal remains the same size but its complexity, accuracy, and precision keeps increasing. As new organizations and technologies push ordinary field and armchair mappers like me out of manual tasks we used to perform, we continue to push the boundaries of what can be mapped, what can be articulated about the world.

Great Britain’s coastline
Great Britain’s coastline, measured at decreasing scale but increasing complexity, Alexandre Van de Sande, GFDL 1.2 or CC BY-SA 3.0

A complete map

Posted by Minh Nguyen on 24 August 2015 in English (English). Last updated on 6 May 2017.

I saved my 10,000th changeset yesterday, as part of a months-long surveying and mapping spree in San José, California, where I currently live.

I never intended to map the Bay Area. Instead, I typically spend my free time helping to map my hometown of Cincinnati and tame TIGER deserts elsewhere in Ohio from the comfort of my (armless) chair. I always assumed that the middle of Silicon Valley would be full of tech enthusiasts who occupy their time by micromapping every last bench and bush. The map sure looked complete, with lots of highway=primarys and highway=secondarys, landuse areas covering every square inch, and plenty of rail and bike infrastructure.

But then, in April, I zoomed in. I had recently joined Mapbox to work on iOS map software, and the Show My Location function went right to my unmapped doorstep. Around me was an endless parade of outdated street configurations, missing landmarks, test edits, proposed BART stations tagged as the real thing, and GNIS-imported hospitals that had been closed for years. Most of the map hadn’t been touched in six years. In terms of POIs like shops and restaurants, central San José in 2015 was as blank as Cincinnati was in 2008. (San José is the country’s tenth-largest city, with a population 3½ times that of Cincinnati.)

Zoom in all the way to the spot marked San José, and this is what you would’ve found earlier this year.

As I added in pent-up local knowledge, I couldn’t help but notice some unfortunate tagging practices. The Bay Area is (ahem) liberal in its use of highway=primary and highway=secondary. It wasn’t difficult to find quiet residential roads with speed bumps, Child at Play signs, or unsignalized crosswalks being tagged as secondary, the same tag often used for heavily-used roads in other cities or 55 mph state highways in rural areas.

Most of the giant landuse areas that blanket the city need to be redrawn. Many landuse=residential areas conflate distinct neighborhoods or include tree-lined business districts (which look like residential areas from the air). Meanwhile, many industrial areas are being converted into residential areas due to a local housing boom. As much as possible, I’m replacing these generic landuse areas with more specific ones that correspond to individually named subdivisions, office parks, and retail complexes.

A typical landuse=residential area in San José spans multiple highway=primary roads. Either these aren’t really primary roads or this isn’t really one coherent residential area.

I suspect that the highway classifications and generic landuse areas, combined with decent rail data, made the map look a lot more complete than it really was. To a newcomer, the total absence of restaurants, buildings, and non-armchair-mappable information might’ve looked like a limitation of the project rather than a blank slate waiting to be edited. And again, there should be no shortage of visitors from San José, because this is Silicon Valley, where people talk about things like OSM. I’m sure the original mappers were doing their best at the time; unfortunately, six years ago, none of us knew as much about mapping ago as we do now.

San José is looking a lot better after an intense few months of surveying. There are plenty of POIs downtown – too many to fit onto the map at z19, in fact – as well as invisible attributes like speed, weight, height, and turn restrictions. I’m having particular fun mapping the many ethnic enclaves around town, which are very poorly represented on commercial map services.

This popular ethnic strip mall is now fully mapped in OSM (seen here in iD at z20). Apple and Google make a mess of things.

The San José place=city POI incorrectly sat 12 blocks away from where it should’ve been, at the site of this church, which incidentally is missing from Apple, Google, and HERE.

dgsmetoc name
Meanwhile, OSM now includes that church, as well as its full Amharic Ethiopian name. (Deciphering the Amharic signage was a challenge in itself.)

Still, that’s only one city. We’ve always known TIGER deserts are a problem, but are other cities similarly languishing after an initial burst of detail, flying under the radar because we all think they’re being taken care of? Maybe we can prevent that from happening in the future by making the map look only as complete as it really is.

Location: Downtown Historic District, San Jose, Santa Clara County, California, 95113, United States

Globalizing the name translation debate

Posted by Minh Nguyen on 5 June 2015 in English (English). Last updated on 6 June 2015.

The world is messy and human languages moreso. Recently the talk@ mailing list erupted in discussion over a proposal to shunt the vast majority of name:* tags over to Wikidata. But most of the discussion has centered around rather eurocentric examples and concerns. I worry that the discussion will lead to a policy change based on overgeneralizations. Having done a fair amount of multilingual name-tagging in the past, I want to point out just a few of the complications that monolingual mappers may be unaware of.

Translation versus transliteration

The top 20 languages are each natively spoken by about one percent of the world’s population. Twelve of them are in scripts other than Latin, and at least three are in non-alphabetic scripts, requiring transliteration just to produce a name that monolingual English speakers can recognize as text, let alone type.

Some have argued that translations are preferable to transliterations. Others have argued that transliterations should be omitted entirely from OSM, as an exercise to the reader or a job for third-party services. But what’s the difference between translation and transliteration? The wiki offers this simplistic explanation:

Transliteration is the process of taking a name in one language, and simply changing letters from one script to another.

This definition is a gross oversimplification, downplaying what it takes to adapt a foreign word to something you can use in your own language. There are three ways to go about it:

  • Transcription from another language gets you the original word’s pronunciation respelled in a very literal phonetic alphabet (or a language-neutral alphabet like the IPA), without regard for etymology. Except for cases involving ideographic scripts, as we’ll see below, pure transcription is almost never the right answer for a name:* tag.
  • Transliteration from another script to a Roman alphabet gets you the original word, but respelled as if English had borrowed the word, often taking liberties with the pronunciation in order to look “native” or respect the original etymology. Transliteration is the most reliable method for producing a usable name in your language.
  • Translation from another language to English gets you a word that refers to the same thing in English but may have a completely different pronunciation and etymology. Translation is only appropriate in a limited number of cases for historical reasons. Words like “north” and “city” are often translated while the rest of the name is transliterated.

I don’t speak Russian; perhaps one can get Абергавенни from “Abergavenny” by performing a simple one-to-one mapping from Cyrillic letters to Latin letters. But Russian has varying transliteration schemes, each with their own exceptions, and that’s a relatively easy task considering that the Roman and Cyrillic scripts share a common ancestor.

A counterexample: transliterating Chinese to Vietnamese

Shanghai Railway Station façade
Shanghai has a Vietnamese name. You’ll never see it on signage in Shanghai, but no Vietnamese speaker refers to the city by its Chinese name. (Photo: Immanuel Giel / CC BY-SA 4.0)

Over the last seven years, I’ve added tens of thousands of name:vi tags by hand, the vast majority of them to place POIs and relations in mainland China. One of these POIs is Shanghai, called 上海 in Chinese. English-language literature calls it “Shanghai”, after the Pinyin transcription Shànghǎi. Shanghai is just a name to English speakers; it retains the pronunciation, more or less, but not the meaning. A literal translation would be “High Sea” or, more poetically, “Upon the Sea”. You’d never put “Upon the Sea” into OpenStreetMap because no one has ever called it that. You’d set name:en=Shanghai because English has no special name for the city.

Vietnamese is very different when it comes to Chinese names. Vietnam has had millennia of intense contact with China (much of it adversarial). As a result, every Chinese character has a Sino-Vietnamese reading: a word that was borrowed from Middle Chinese into Old Vietnamese, retaining the meaning but not the pronunciation (owing to changes in both spoken Vietnamese and spoken Chinese over the centuries). For Shanghai, I set name:vi=Thượng Hải, using Sino-Vietnamese for 上海. It literally means “high sea”, but in words that are only used for terms and names borrowed from Chinese.

As it happens, 上 has multiple readings corresponding to different meanings: thưởng (award), thượng (high), thướng (rise). Choosing between them is the task of a translator, not a SQL transform. So how does a translator like me know choose the right Sino-Vietnamese words? Sometimes the answer is obvious: I simply learned long ago that Shanghai is called Thượng Hải in the course of learning Vietnamese, and most Vietnamese learn that just by living in Vietnam for a time. For more obscure names, there are plenty of places to look up individual characters. My sources have included an out-of-copyright dictionary and a Sino-Vietnamese database that comes with no restrictions according to its author. (For the record, Unihan is TIGER bad when it comes to Vietnamese.) When I’m on the fence about a transliteration, I double-check it against sites like the Vietnamese Wikipedia. And when a character really has me stumped, I leave the POI alone.

If I were to actually translate “Shanghai” into “plain” Vietnamese, the result would be either Trên Biển if I transliterate at the same time or something like 𨕭𣛟 if I don’t. (The Vietnamese language also used ideographic characters until the 20th century, just a different set of characters than Chinese.) No one would ever use the “plain” Vietnamese name, though; Thượng Hải is the only correct way to render this particular city’s name in Vietnamese.

This is just one language out of many that have rich histories of dealing with multiple writing systems. You can imagine that other languages have their own unique considerations.

Machine transliteration is impractical

If we rely on software to localize place names for us, some languages can hope for no better than hack jobs, akin to this humorous map in “English”. (Illustration: imkharn)

There has been plenty of handwaving about renderers and geocoders that are smart enough to transliterate between different writing systems. But consider that Google Translate, with all its NLP might and a corpus the size of the Internet, fares poorly at interpreting Chinese place names. It doesn’t know that 红寺堡 is Hồng Tự Bảo in Vietnamese or “Hongsibao” in English. Your average mapmaker can’t afford that kind of technology anyways.

Software developers have much more experience converting between metric and imperial units than between human languages. Even though Sino-Vietnamese words aren’t “plain”, modern Vietnamese words, their meanings are often not lost on Vietnamese speakers today. Any schoolchild could tell you that thượng hải means trên biển (upon the sea), an apt name for a major port city. But a multilingual software client, burdened with the knowledge that thượng could also mean 㐀 = “hill”, or 㠪 = “five”, or 尙 = “yet”, would need a lot of resources to make a decision:

  1. Natural language processing (NLP), a form of artificial intelligence
  2. Context about the city and common naming practices
  3. A decent, machine-readable, suitably licensed dictionary for that particular language pair
  4. Possibly even dedicated logic for each character, multiplied by the number of transliteration schemes

Then there are suggestions that IPA transcriptions could be tagged as an intermediate step. But IPA comes with its own headaches, like whether to transcribe broadly or narrowly. Consider the number of valid English pronunciations of “north”, then consider that the same Chinese script is used by a host of mutually-unintelligible language varieties.

It wouldn’t be possible to derive the Sino-Vietnamese name from an IPA or Pinyin transcription, anyways, because they have different many-to-many mappings between characters and words. Shàng (Pinyin) doesn’t just correspond to 上; it also corresponds to the following characters, as would an IPA transcription based on Mandarin: 上姠尙尚蠰銄鑜. On the other hand, thượng (Sino-Vietnamese) corresponds to a very different set of Chinese characters: 㐀㠪丄仩上鞜妴尙尚鞝躺𠄞. Spoken Mandarin and Vietnamese have evolved so much over the centuries that, if a system like Sino-Vietnamese were invented today based on modern Mandarin pronunciation instead of Middle Chinese, it would employ a completely different set of words for each character.

There is a consensus at least that automatic transliteration does not belong in OSM, because it cannot be verified for accuracy. But excluding handcrafted transliterations from OSM forces data consumers to foist those same automatic, unverified algorithms upon their users. The result is the worst of both worlds: poor support due to the effort required and poor quality due to a lack of context.


Posted by Minh Nguyen on 13 October 2014 in English (English). Last updated on 9 February 2018.

Warning: This post makes absolutely no sense to anyone outside the United States, or to anyone who relies on a mode of transportation that uses a sane numbering scheme.

Development on the OSM U.S. shield renderer seems to have stalled a bit, and my request to render pictoral route shields on the Standard stylesheet is effectively tabled for now. There doesn’t seem to be a whole lot to get excited about on the shield rendering front.

Just to bide my time, I decided to approach route shields from the other direction, using OpenStreetMap’s coverage of the Cincinnati Tri-State area as a starting point. Slapping shields in random locations all over a road map is so… functional. So let’s ditch the map, fire up TileMill, and let the shields do the talking:

The first thing you see

A bit of a mess, isn’t it? It’s even worse when you zoom out:

The next thing you see

But pan around, and you might start to notice some patterns if you’re from the area. You can make out the most prominent highways. Here’s a map Nate made from OSM data, for comparison:

Back to reality

You can make out the Ohio–Kentucky state line where the state route shields in the shape of Ohio turn into plain old circles:

These states have a lot in common, really

So what’s going on? Each shield on the grid indicates the nearest Interstate, U.S. route, or state route, with an understandable bias towards highways over surface streets. A shield isn’t necessarily positioned along the route it indicates; rather, it just happens that no other route is closer. That property gives rise to an interesting phenomenon that I’ll take the liberty of calling a routeshed. Much like a watershed, a routeshed encompasses the area in which cars naturally flow toward a single route. OK, that sounds so ridiculous it belongs in a Wikipedia article. But this is what the sparse terrain of western Hamilton County looks like:

No choice but the Interstate

If you’re as sleep-deprived as I am, it does kinda-sorta look like a watershed.

Here’s the full slippy map.

Credits: Road data from OpenStreetMap contributors, mostly me, Nate, and NE2. Shield blanks from Wikimedia Commons users SPUI, Ltljltlj, Fredddie, and Scott5114. Shield labels set in Roadgeek 2005 Series C and D. Code under the MIT license; tiles under Creative Commons Attribution 4.0.

Location: Betts-Longworth Historic District, West End, Cincinnati, Hamilton County, Ohio, 45214-2592, United States

U.S. highway coordination

Posted by Minh Nguyen on 13 April 2009 in English (English).

Just a heads-up to mappers in the United States: we’re starting to tag highways with relation:route (see the tagging guide). Entire highways will be joined with one (two?) relations. Because Interstate highways and U.S. Routes cross state lines, we’re trying to coordinate our efforts with two wiki pages:

One of the driving forces for using relations is that we can cleanly handle concurrencies. Eventually, we can also look forward to custom highway shields like we’re used to seeing on virtually all other maps. Looks like it hasn’t been mentioned on Planet OSM yet, but here’s a nice demo of the shields being rendered.

Dorm OSM tutorial

Posted by Minh Nguyen on 4 February 2009 in English (English).

Tonight I organized a brief tutorial on contributing to OpenStreetMap at my dorm. My dormmates raised some good questions that I didn’t have the answers to off the top of my head. One of the questions was whether there was a way to tag historical features that are now gone. Besides railroad rights-of-way and the old_name key, I couldn’t think of a general way to map features that are entirely gone. I also fielded the standard questions about vandalism.

Location: Lucie Stern Hall, Stanford, Santa Clara County, California, United States

Nothing to see here

Posted by Minh Nguyen on 5 December 2008 in English (English). Last updated on 25 January 2017.

A traveling salesman plans to attend a conference of traveling salesmen and wants to drive from point A to point B and back using the shortest, quickest route possible. He first tries the obvious tool for the job, Google Maps, which times out unexpectedly. Yahoo! Maps, Live Maps, and MSN Maps all do likewise when given the same query. MapQuest returns a more helpful 500 Internal Server Error after a few minutes.

In a fit of desperation, he consults OpenStreetMap, which routes him through null and undefined. The traveling salesman is now enlightened about the NP-hard class of problems.

Edited 24 January 2017: Replaced OSM Gazetteer links with Nominatim links.