[{"data":1,"prerenderedAt":265},["ShallowReactive",2],{"footer-learn-links":3,"site-prefooter-cta":16,"blog-\u002Fblog\u002Frevisiting-the-cartography-behind-stamen-terrain\u002F":24,"related-blog-\u002Fblog\u002Frevisiting-the-cartography-behind-stamen-terrain\u002F":209,"blog-author-\u002Fblog\u002Frevisiting-the-cartography-behind-stamen-terrain\u002F":254},[4,7,10,13],{"title":5,"path":6},"What Does a \"Free\" Map API Actually Cost?","\u002Flearn\u002Fwhat-does-a-free-map-api-cost",{"title":8,"path":9},"What Is the Best Geocoding API?","\u002Flearn\u002Fbest-geocoding-api",{"title":11,"path":12},"What Is the Best Routing API?","\u002Flearn\u002Fbest-routing-api",{"title":14,"path":15},"What Is a GDPR-Compliant Mapping API?","\u002Flearn\u002Fgdpr-compliant-mapping-api",{"id":17,"extension":18,"heading":19,"meta":20,"stem":21,"text":22,"__hash__":23},"site\u002Fsite\u002Fprefooter-cta.yml","yml","Business Outcomes That Fuel Your Growth",{},"site\u002Fprefooter-cta","With Stadia Maps, you build the solutions that matter. Logistics platforms provide accurate ETAs, fleet management apps reduce fuel costs, and emergency dispatch systems improve response times.","XztWiZDFyAC0XCoeYLLQrcyaVmP8uvGWALRS354c9I4",{"id":25,"title":26,"abstract":27,"author":28,"body":29,"description":184,"extension":185,"head":27,"image":186,"imageAlt":187,"keywords":188,"meta":198,"modified":27,"navigation":199,"path":200,"proficiencyLevel":27,"published":201,"rawbody":202,"schemaOrg":27,"schemaType":27,"section":203,"seo":204,"stem":207,"__hash__":208},"blog\u002Fblog\u002Frevisiting-the-cartography-behind-stamen-terrain.md","Revisiting the Cartography Behind Stamen Terrain",null,"ian-wagner",{"type":30,"value":31,"toc":177},"minimark",[32,36,54,57,60,63,66,69,80,85,88,93,98,103,107,112,116,121,125,128,131,137,141,156,169],[33,34,26],"h1",{"id":35},"revisiting-the-cartography-behind-stamen-terrain",[37,38,39],"blockquote",{},[40,41,42,43,48,49,53],"p",{},"We've been taking a fresh look at the cartographic decisions at every level of our map stack. Our recent ",[44,45,47],"a",{"href":46},"\u002Fblog\u002Ffixing-missing-water-interactive-basemaps\u002F","water layer changes"," and ",[44,50,52],{"href":51},"\u002Fblog\u002Fwater-labels-reworked-cleaner-names-smarter-placement\u002F","water label updates"," made a visible difference to the Stamen Terrain style.",[40,55,56],{},"Rendering water at low- to mid-zoom levels trades detail against tile size. We want to represent the important features without bloating the tiles with irrelevant detail.",[40,58,59],{},"For polygonal features like water bodies, there already exist several generalized, pre-processed global datasets at varying levels of detail. We used these in the past, but found these created visual jumps when going from one zoom level to the next.",[40,61,62],{},"This was sometimes because of incompatible generalization strategies. For example, many low-resolution water datasets intentionally leave out minor features like fjords, which are not strictly important for a general large-area map but are still visible from a great distance. This is fine for their intended use case, but problematic for ours.",[40,64,65],{},"The other broad class of problem we noticed was that switching datasets (e.g., between Natural Earth and OSM) caused larger discontinuities, as the datasets were produced independently and vary at different speeds. We addressed this by processing OSM data for every zoom level. This took some more work to process, but was absolutely worth it!",[40,67,68],{},"For line data, the generalization criteria are different. We, of course, want to simplify the overall shape using similar techniques to those for polygons, but \"importance\" is a bit more difficult to measure. We revisited the thresholds for inclusion at every zoom level.",[40,70,71,72,79],{},"The differences in ",[44,73,75],{"href":74},"\u002Fexplore-the-map\u002F#style=stamen_terrain&map=10.05\u002F47.3495\u002F9.3513",[76,77,78],"strong",{},"Stamen Terrain"," were striking enough that we've put together this screenshot tour.",[81,82,84],"h2",{"id":83},"whats-changed","What's Changed",[40,86,87],{},"Below are four side-by-side comparisons of the former style and the new revised version. We used Iceland, Norway, a wider view of Scandinavia, and Lake Ontario as examples. Drag the slider to compare each pair directly.",[40,89,90],{},[76,91,92],{},"Iceland",[94,95],"content-twenty-twenty",{"after-src":96,"before-src":97},"\u002Fimages\u002Fcontent\u002Ficeland-after.png","\u002Fimages\u002Fcontent\u002Ficeland-before.png",[40,99,100],{},[76,101,102],{},"Norway",[94,104],{"after-src":105,"before-src":106},"\u002Fimages\u002Fcontent\u002Fnorway-after.png","\u002Fimages\u002Fcontent\u002Fnorway-before.png",[40,108,109],{},[76,110,111],{},"Scandinavia",[94,113],{"after-src":114,"before-src":115},"\u002Fimages\u002Fcontent\u002Fscandinavia-after.png","\u002Fimages\u002Fcontent\u002Fscandinavia-before.png",[40,117,118],{},[76,119,120],{},"Lake Ontario",[94,122],{"after-src":123,"before-src":124},"\u002Fimages\u002Fcontent\u002Flake-ontario-after.png","\u002Fimages\u002Fcontent\u002Flake-ontario-before.png",[40,126,127],{},"Across all examples, we've been able to preserve more detail. And, while it's harder to highlight the difference here, we've removed essentially all discontinuous coastline and waterway jumps between zoom levels.",[40,129,130],{},"Somewhat counterintuitively, this update actually reduces vector tile size at lower zoom levels. Even though we increased the level of visual detail on the map, we got much smarter about merging contiguous bodies of water. And of course, we were also able to drop insignificant features more reliably and improve our approach to geometric simplification, both of which contributed to the reduced tile sizes.",[40,132,133,134],{},"If you look closely, you might also notice some differences in water labels between the before and after images. ",[44,135,136],{"href":51},"You can read more about our recent overhaul of water name labeling here.",[81,138,140],{"id":139},"what-this-means-for-your-application","What This Means for Your Application",[40,142,143,144,147,148,155],{},"If you're using ",[44,145,78],{"href":146},"\u002Fproducts\u002Fmaps\u002Fmap-styles\u002F",", whether vector or raster, via the endpoints on our ",[44,149,154],{"href":150,"rel":151,"target":153},"https:\u002F\u002Fdocs.stadiamaps.com\u002Fmap-styles\u002Fstamen-terrain\u002F",[152],"external","_blank","Stamen Terrain style page",", you're automatically getting the improved tiles. No changes needed on your end.",[157,158,159,163,166],"ul",{},[160,161,162],"li",{},"Water bodies and coastlines render more consistently across zoom levels, with less of the visual noise that comes from switching data sources mid-zoom",[160,164,165],{},"Lower-zoom tiles are smaller, despite showing more visual detail",[160,167,168],{},"Improved water feature labeling: maps now show significant bays, lakes, and gulfs at lower zoom levels; show labels for straits (these were not present before); and have cleaner labels for major oceans and seas",[40,170,171,172,176],{},"Follow us for more updates as we continue updating our cartography. And if you spot anything that looks off, let us know at ",[44,173,175],{"href":174},"mailto:support@stadiamaps.com","support@stadiamaps.com",".",{"title":178,"searchDepth":179,"depth":179,"links":180},"",4,[181,183],{"id":83,"depth":182,"text":84},2,{"id":139,"depth":182,"text":140},"Our recent water layer and water label changes reshaped how Stamen Terrain renders coastlines, fjords, and lakes. Four before-and-after comparisons show the difference.","md","\u002Fimages\u002Fog\u002Frevisiting-the-cartography-behind-stamen-terrain.png","Revisiting the Cartography Behind Stamen Terrain — Stadia Maps",[78,189,190,191,192,193,194,195,196,197],"map cartography","water rendering","vector tiles","coastline generalization","zoom level discontinuities","OpenStreetMap water data","Natural Earth","tile size","basemap styles",{},true,"\u002Fblog\u002Frevisiting-the-cartography-behind-stamen-terrain","2026-09-14","---\ntitle: Revisiting the Cartography Behind Stamen Terrain\ndescription: Our recent water layer and water label changes reshaped how Stamen Terrain renders coastlines, fjords, and lakes. Four before-and-after comparisons show the difference.\nauthor: ian-wagner\nimage: \u002Fimages\u002Fog\u002Frevisiting-the-cartography-behind-stamen-terrain.png\nimageAlt: Revisiting the Cartography Behind Stamen Terrain — Stadia Maps\nkeywords:\n  - Stamen Terrain\n  - map cartography\n  - water rendering\n  - vector tiles\n  - coastline generalization\n  - zoom level discontinuities\n  - OpenStreetMap water data\n  - Natural Earth\n  - tile size\n  - basemap styles\npublished: 2026-09-14\nsection: Maps\nseo:\n  title: \"Stamen Terrain: Improved Water Rendering\"\n  ogTitle: Revisiting the Cartography Behind Stamen Terrain\n  description: How processing OSM water data at every zoom level removed coastline jumps in Stamen Terrain, preserved more detail, and shrank low-zoom vector tiles.\n---\n\n# Revisiting the Cartography Behind Stamen Terrain\n\n> We've been taking a fresh look at the cartographic decisions at every level of our map stack. Our recent [water layer changes](\u002Fblog\u002Ffixing-missing-water-interactive-basemaps\u002F) and [water label updates](\u002Fblog\u002Fwater-labels-reworked-cleaner-names-smarter-placement\u002F) made a visible difference to the Stamen Terrain style.\n\nRendering water at low- to mid-zoom levels trades detail against tile size. We want to represent the important features without bloating the tiles with irrelevant detail.\n\nFor polygonal features like water bodies, there already exist several generalized, pre-processed global datasets at varying levels of detail. We used these in the past, but found these created visual jumps when going from one zoom level to the next.\n\nThis was sometimes because of incompatible generalization strategies. For example, many low-resolution water datasets intentionally leave out minor features like fjords, which are not strictly important for a general large-area map but are still visible from a great distance. This is fine for their intended use case, but problematic for ours.\n\nThe other broad class of problem we noticed was that switching datasets (e.g., between Natural Earth and OSM) caused larger discontinuities, as the datasets were produced independently and vary at different speeds. We addressed this by processing OSM data for every zoom level. This took some more work to process, but was absolutely worth it!\n\nFor line data, the generalization criteria are different. We, of course, want to simplify the overall shape using similar techniques to those for polygons, but \"importance\" is a bit more difficult to measure. We revisited the thresholds for inclusion at every zoom level.\n\nThe differences in [**Stamen Terrain**](\u002Fexplore-the-map\u002F#style=stamen_terrain&map=10.05\u002F47.3495\u002F9.3513) were striking enough that we've put together this screenshot tour.\n\n## What's Changed\n\nBelow are four side-by-side comparisons of the former style and the new revised version. We used Iceland, Norway, a wider view of Scandinavia, and Lake Ontario as examples. Drag the slider to compare each pair directly.\n\n**Iceland**\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Ficeland-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Ficeland-before.png\"}\n\n**Norway**\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Fnorway-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Fnorway-before.png\"}\n\n**Scandinavia**\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Fscandinavia-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Fscandinavia-before.png\"}\n\n**Lake Ontario**\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Flake-ontario-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Flake-ontario-before.png\"}\n\nAcross all examples, we've been able to preserve more detail. And, while it's harder to highlight the difference here, we've removed essentially all discontinuous coastline and waterway jumps between zoom levels.\n\nSomewhat counterintuitively, this update actually reduces vector tile size at lower zoom levels. Even though we increased the level of visual detail on the map, we got much smarter about merging contiguous bodies of water. And of course, we were also able to drop insignificant features more reliably and improve our approach to geometric simplification, both of which contributed to the reduced tile sizes.\n\nIf you look closely, you might also notice some differences in water labels between the before and after images. [You can read more about our recent overhaul of water name labeling here.](\u002Fblog\u002Fwater-labels-reworked-cleaner-names-smarter-placement\u002F)\n\n## What This Means for Your Application\n\nIf you're using [Stamen Terrain](\u002Fproducts\u002Fmaps\u002Fmap-styles\u002F), whether vector or raster, via the endpoints on our [Stamen Terrain style page](https:\u002F\u002Fdocs.stadiamaps.com\u002Fmap-styles\u002Fstamen-terrain\u002F), you're automatically getting the improved tiles. No changes needed on your end.\n\n- Water bodies and coastlines render more consistently across zoom levels, with less of the visual noise that comes from switching data sources mid-zoom\n- Lower-zoom tiles are smaller, despite showing more visual detail\n- Improved water feature labeling: maps now show significant bays, lakes, and gulfs at lower zoom levels; show labels for straits (these were not present before); and have cleaner labels for major oceans and seas\n\nFollow us for more updates as we continue updating our cartography. And if you spot anything that looks off, let us know at \u003Csupport@stadiamaps.com>.\n","Maps",{"title":205,"ogTitle":26,"description":206},"Stamen Terrain: Improved Water Rendering","How processing OSM water data at every zoom level removed coastline jumps in Stamen Terrain, preserved more detail, and shrank low-zoom vector tiles.","blog\u002Frevisiting-the-cartography-behind-stamen-terrain","11O4tHId1IcY7X0BkTd6kfK2Y_TsFZR9u4JGbQKzQMQ",[210,225,237],{"title":211,"description":212,"path":213,"published":214,"keywords":215,"rawbody":224},"Water Labels Reworked: Cleaner Names, Smarter Placement, and Straits at Last","We overhauled water name labeling across our basemaps with better relevance in the tiles, cleaner names for seas and oceans, centered lake labels, and straits.","\u002Fblog\u002Fwater-labels-reworked-cleaner-names-smarter-placement","2026-08-24",[216,189,217,191,218,219,220,221,222,223],"water labels","water_name layer","label placement","symbol-placement line-center","OpenStreetMap water names","straits","map label language","basemap styling","---\ntitle: \"Water Labels Reworked: Cleaner Names, Smarter Placement, and Straits at Last\"\ndescription: We overhauled water name labeling across our basemaps with better relevance in the tiles, cleaner names for seas and oceans, centered lake labels, and straits.\nauthor: ian-wagner\nimage: \u002Fimages\u002Fog\u002Fwater-labels-reworked.png\nimageAlt: \"Water Labels Reworked: Cleaner Names, Smarter Placement, and Straits at Last — Stadia Maps\"\nkeywords:\n  - water labels\n  - map cartography\n  - water_name layer\n  - vector tiles\n  - label placement\n  - symbol-placement line-center\n  - OpenStreetMap water names\n  - straits\n  - map label language\n  - basemap styling\npublished: 2026-08-24\nsection: Maps\nseo:\n  title: Water Label Improvements in Basemaps\n  ogTitle: Water Labels Reworked\n  description: Better relevance selection, cleaner names for major water bodies, centered lake labels, and straits are now in the water_name layer. Here's what changed and what to check in custom styles.\n---\n\n# Water Labels Reworked: Cleaner Names, Smarter Placement, and Straits at Last\n\n> Around 71% of the Earth's surface is covered in water. It's not something everyone thinks about when they look at their maps, but bodies of water also provide important locational context. We're in the process of reworking our cartography from the ground up. Here are some details about our recent overhaul of water name labeling.\n\n## What We Changed\n\nThe way we approached water labeling hasn't changed much since we launched around a decade ago. I had been keeping a laundry list of things to improve for a while. It started with several variations of \"X should (or should not!) be visible at zoom Y,\" and as I dug deeper, I found a few other things we could bundle into this release.\n\n### 1. Improved relevance selection in our tiles\n\nIf you can see it from space, but it's not visible till z8, that's not great! That was, unfortunately, the story of some of the world's largest lakes, including the Great Lakes and Lake Baikal.\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Fgreat-lakes-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Fgreat-lakes-before.png\"}\n\nThe main fix here was considering a better set of factors when determining relevance. This is baked into our tile build process, so styles don't need to make any changes.\n\nWhile you may (correctly) guess that this includes more features in the low-detail tiles, we saw an unexpected improvement in tile sizes through the mid to high detail levels. We previously included many irrelevant features at mid-zoom levels. These caused frequent collisions between lower relevance labels and higher relevance ones. Removing these reduced the overall tile size and resulted in more relevant labels showing up.\n\n### 2. Cleaner labels for major water bodies\n\nWe cleaned up labels for large maritime areas and inland seas.\n\nOne of our guiding cartographic principles is to display labels in the local language by default wherever possible. In most of the world, signage is only displayed in a single language\u002Fscript, so our maps default to showing that. We may also display a \"Latin script\" name for some features to improve international readability if the place has a name in another language, like English or French.\n\nInternational waters are tricky, though, since there is no \"local language\" and they aren't part of any one country. In OpenStreetMap, these are often given a `name` tag with half a dozen languages, separated by… something. This is not always consistent, makes the map harder to read, and crowds out other labels that could provide relevant context. In short, it's not great for anyone.\n\nWe've simplified our default styling to just the common English name for these features. Smaller bodies of water like lakes and smaller inland seas will continue to be labeled as-is, with both the local name and optionally a Latinized name.\n\nThis does not change anything about the data that we ship in the vector tiles. We still include dozens of languages, and if you're localizing a map for an audience with different language preferences, you can still [customize the styles to fit your desired label language](https:\u002F\u002Fdocs.stadiamaps.com\u002Ftutorials\u002Fchanging-the-map-label-language\u002F).\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Fcaspian-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Fcaspian-before.png\"}\n\nBesides being cleaner, this also lets us place more labels. Note how the Black Sea was conspicuously absent before. This was because the label would have clashed with Sevastopol, so it got dropped from the middle zoom levels.\n\n### 3. Improved the placement of lake centerline labels\n\nOur in-house map styles labeled lake centerlines inconsistently. They were often off-center at lower zoom levels, and the spacing wasn't consistent.\n\nThis is now fixed, and often results in more lake labels being placeable at medium zoom levels, since moving the label to the center steers clear of settlements bordering the lake. The main fix was changing the `symbol-placement` [property](https:\u002F\u002Fmaplibre.org\u002Fmaplibre-style-spec\u002Flayers\u002F#symbol-placement) from `line` to `line-center` in all of our styles. (The brilliant cartographers over at [Stamen](\u002Fstamen\u002F) actually got this right on the first try, though, so their styles didn't suffer from this issue!)\n\n:content-twenty-twenty{after-src=\"\u002Fimages\u002Fcontent\u002Flake-centerlines-after.png\" before-src=\"\u002Fimages\u002Fcontent\u002Flake-centerlines-before.png\"}\n\n### 4. Straits are here!\n\nThat we never included these in our basemaps was a historical accident. Important straits will appear as `LineString` features in the `water_name` layer, so you get beautiful labels like these.\n\n![Stadia Maps Water Label Update - Straits](\u002Fimages\u002Fcontent\u002Fstraits.png)\n\n## What This Means for You\n\nMost Stadia Maps customers don't need to do anything. If you're using our raster map tiles or a vector style hosted at [tiles.stadiamaps.com](https:\u002F\u002Ftiles.stadiamaps.com), you already have the latest and greatest styling. All the improvements mentioned above are already live.\n\nIf you customized your own style, you may need a few minor tweaks to polish things up. The area around the English Channel highlights the two types of features most likely to require styling adjustments.\n\n![The area around the English Channel highlights the two types of features most likely to require styling adjustments.](\u002Fimages\u002Fcontent\u002Fenglish-channel.png){style=\"display: block; margin-inline: auto; max-width: 100%; width: auto;\"}\n\nIf you don't see the English Channel or the Bay of Biscay, check your style for references to the `water_name` layer and make sure that your class filters include `strait` and `bay` at lower zoom levels (we generally recommend removing zoom-based filters, unless you are intentionally creating a minimalist style). And if your layer for line-based water names doesn't do so already, set the `symbol-placement` to `line-center` to get the same visual improvements we showed above.\n",{"title":226,"description":227,"path":228,"published":229,"keywords":230,"rawbody":236},"How We Fixed Water Feature Rendering Across All Zoom Levels in Our Basemaps","Mixing Natural Earth and OSM data across zoom levels broke rivers, coastlines, and islands. Here's how a single Overture Maps dataset fixed it.","\u002Fblog\u002Ffixing-missing-water-interactive-basemaps","2026-06-04",[203,231,232,233,234,235],"Interactive Basemaps","OpenStreetMap","Overture Maps","Cartography","Vector Tiles","---\ntitle: How We Fixed Water Feature Rendering Across All Zoom Levels in Our Basemaps\ndescription: Mixing Natural Earth and OSM data across zoom levels broke rivers, coastlines, and islands. Here's how a single Overture Maps dataset fixed it.\nauthor: ian-wagner\nimage: \u002Fimages\u002Fog\u002Fwater-basemap-og.png\nimageAlt: How We Fixed Water Feature Rendering Across All Zoom Levels in Our Basemaps — Stadia Maps\nkeywords:\n  - Maps\n  - Interactive Basemaps\n  - OpenStreetMap\n  - Overture Maps\n  - Cartography\n  - Vector Tiles\npublished: 2026-06-04\nsection: Maps\nseo:\n  title: How We Fixed Water Feature Rendering on Our Basemaps\n  ogTitle: How We Fixed Water Feature Rendering Across All Zoom Levels in Our Basemaps\n  ogDescription: Mixing Natural Earth and OSM data across zoom levels broke rivers, coastlines, and islands. Here's how a single Overture Maps dataset fixed it.\n  description: Mixing Natural Earth and OSM data across zoom levels broke rivers, coastlines, and islands. Here's how a single Overture Maps dataset fixed it.\n---\n\n# How We Fixed Water Feature Rendering Across All Zoom Levels in Our Basemaps\n\n> We just shipped a significant update to the data pipeline behind our [Interactive Basemaps](\u002Fproducts\u002Fmaps\u002Finteractive-maps\u002F). The change fixes a class of visual inconsistencies at low- and mid-zoom levels, such as missing rivers, shifting coastlines, islands that suddenly appear, and major water features that pop into detail abruptly rather than transitioning smoothly. The root cause was mixing two different data sources at different zoom levels. The fix is a unified OSM-derived dataset across all zoom levels, sourced from [Overture Maps](https:\u002F\u002Foverturemaps.org\u002F).\n\nHere's what was happening and what we changed.\n\n## Why Water Features Were Disappearing at Mid-Zoom Levels\n\nOur basemaps were pulling from two different datasets, depending on the zoom level. At lower zooms, we used Natural Earth, a well-known dataset that efficiently represents the most important details for broad-scale cartography. At higher zooms, we switched to OSM-derived data. These two datasets don't agree on everything: coastlines have vastly different levels of detail and features that exist in one don't always have equivalents in the other at the same zoom thresholds.\n\nThe handoff point between them was the source of most of the visual inconsistencies. A customer noticed a clear example: The St. Lawrence River disappeared entirely between zooms 6 and 8. OSM represents it as a `water` polygon, while the way we processed Natural Earth's simplified data at those zoom levels didn't carry the equivalent coverage. The result is a river-shaped hole filled with land. But that was one symptom of a broader pattern. Coastlines were shifting shape mid-zoom, small islands were appearing or vanishing, and water features were popping in suddenly rather than transitioning smoothly.\n\n:content-twenty-twenty{after-src=\"\u002Fassets\u002Ficeland-new.png\" before-src=\"\u002Fassets\u002Ficeland-old.png\"}\n\n## What Changed: A Single Data Source Across All Zoom Levels\n\nWe've unified our basemaps around a single OSM-derived dataset across all zoom levels. Specifically, we're using releases from [Overture Maps](https:\u002F\u002Foverturemaps.org\u002F), which apply additional QA on top of OSM to ensure major water bodies are complete and consistent, something we had occasionally struggled with when building directly from raw OSM data.\n\nUsing the same source throughout eliminates the cross-dataset seam. No more coastline jumps. No more islands appearing from nowhere. No more rivers losing their shape at mid-zoom. It also means features that were simply absent at lower zoom levels. Rivers, estuaries, and reservoirs are now present and correct from the moment they're geographically relevant, rather than popping in abruptly as you zoom past the old data handoff point.\n\nWe also updated our geometry simplification algorithm and parameters. The new approach carries more detail through mid-zoom levels and produces smoother transitions as you zoom in and out with less of the sudden snap from one level of detail to the next.\n\nThe St. Lawrence is back where it belongs: [see it here](\u002Fexplore-the-map\u002F#map=8.86\u002F44.5347\u002F-75.4982).\n\n## What This Means for Your Application\n\nIf your application renders maps at mid-zoom levels, your users are now seeing more accurate, more consistent water rendering. Specifically:\n\n- **Rivers, estuaries, and reservoirs** now appear at the zoom levels where they're geographically relevant\n- **Coastlines** have smoother transitions, with more detail present at low and mid zoom levels\n- **Islands and water bodies** render consistently from zoom to zoom\n- **Transitions between zoom levels** are smoother across all water features\n\nThese are the kinds of artifacts that are easy to miss in development and easy to notice in production. If you ever spot anything on the map that still looks off, let us know at \u003Csupport@stadiamaps.com>. Reports like these are how this fix started.\n",{"title":238,"description":239,"path":240,"published":241,"keywords":242,"rawbody":253},"Choosing the Right Geocoding Endpoint","Forward or reverse? Search, structured, or autocomplete? A practical guide to picking the right Stadia Maps geocoding endpoint for your application.","\u002Fblog\u002Fchoosing-the-right-geocoding-endpoint","2026-09-08",[243,244,245,246,247,248,249,250,251,252],"geocoding endpoint","forward geocoding","reverse geocoding","autocomplete search API","structured geocoding","address validation","checkout form address","house number interpolation","coarse reverse geocoding","bulk geocoding","---\ntitle: Choosing the Right Geocoding Endpoint\ndescription: Forward or reverse? Search, structured, or autocomplete? A practical guide to picking the right Stadia Maps geocoding endpoint for your application.\nauthor: ian-wagner\nimage: \u002Fimages\u002Fog\u002Fchoosing-the-right-geocoding-endpoint.png\nimageAlt: Choosing the Right Geocoding Endpoint — Stadia Maps\nkeywords:\n  - geocoding endpoint\n  - forward geocoding\n  - reverse geocoding\n  - autocomplete search API\n  - structured geocoding\n  - address validation\n  - checkout form address\n  - house number interpolation\n  - coarse reverse geocoding\n  - bulk geocoding\npublished: 2026-09-08\nsection: Geocoding\nseo:\n  title: \"Forward vs. Reverse Geocoding: Choosing an Endpoint\"\n  ogTitle: Choosing the Right Geocoding Endpoint\n  description: When to use search, structured, or autocomplete for forward geocoding, when reverse geocoding is the right call, and how to handle checkout address validation.\n---\n\n# Choosing the Right Geocoding Endpoint\n\n> Geocoding APIs can be broadly split two ways: Forward geocoding turns free text (like an address or place name) into coordinates, and reverse geocoding goes the opposite direction. Understanding the distinction between the two styles is relatively straightforward, but choosing the right endpoint and parameters can make a big difference.\n\nHere's a guide to help you pick the best endpoint for your application.\n\n## Explaining Forward and Reverse Geocoding\n\n**Forward geocoding** maps from natural language inputs to a location. A user types \"1600 Pennsylvania Ave, Washington, DC\", and the API returns what you need to put a pin on the map. And that's not all! Forward geocoding fills in additional information about each \"hit,\" like country, region, and sometimes postal code. All in ways that you can cross-reference against other open datasets.\n\n**Reverse geocoding** turns coordinates into a human-readable description. Whether it's a GPS tracker recording a driver's position, a dashboard grouping events by city, or a mobile app determining the closest street address, the input is geographic coordinates. Filtering to administrative layers (\"country, region, county, locality\") is all you need for analytical groupings by country or region (and it's super fast!). And if you need something more precise, you can filter results to the street, address, or POI layer.\n\nThe choice between forward geocoding and reverse geocoding is usually clear based on the shape of your data and what you're trying to answer. Forward geocoding has a bit more nuance.\n\n## Understanding Forward Geocoding Endpoints\n\nOur [Forward Geocoding API](https:\u002F\u002Fdocs.stadiamaps.com\u002Fgeocoding-search-autocomplete\u002Fsearch\u002F) has three endpoints: **search**, **structured**, and **autocomplete**.\n\n| Endpoint         | Optimized for                      | Key Tradeoffs                                                                                       |\n| ---------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |\n| **Autocomplete** | Type-as-you-search UI              | Fast, but can't interpolate house numbers; direct matches only                                      |\n| **Structured**   | Form-based input (discrete fields) | Best quality for address searches, but requires structured data (no free-form text)                 |\n| **Search**       | Free-text, natural language        | Assumes that input is complete (not search-as-you-type); occasionally mis-parses address components |\n\n**Autocomplete** is built for a type-as-you-search UI. It's optimized for speed and tries to provide the best results given incomplete input (e.g., \"New Y\" will return \"New York\"). Autocomplete can search all layers well and is a great fit when searching for either POIs or addresses interactively. The main tradeoff of autocomplete is that it can't guess interpolated house numbers… yet! You can work around this by hitting the **search** endpoint after some delay, or when the user presses the search button or enter key. We built this behavior into our [search SDKs](https:\u002F\u002Fdocs.stadiamaps.com\u002Fsdks\u002Foverview\u002F#autocomplete-search) for you, including both [SwiftUI](https:\u002F\u002Fdocs.stadiamaps.com\u002Fsdks\u002Fswiftui-autocomplete-search\u002F) and [Jetpack Compose](https:\u002F\u002Fdocs.stadiamaps.com\u002Fsdks\u002Fjetpack-compose-autocomplete-search\u002F).\n\nOur [Autocomplete Search API](\u002Fproducts\u002Fgeocoding-search\u002Fautocomplete-search\u002F) is also *very* efficient: both for your user's network bandwidth and your wallet. Most of the intermediate keystrokes in a search-as-you-type UX aren't valuable to your users, and we understand that. The API returns only the minimal information you'd need to build your search UI and costs only a fraction of the other APIs. When the user selects a result, you call the **place details** API to get the full details. Our search SDKs also handle this for you out of the box.\n\n**Structured geocoding** is optimized for address searches where you know what components your inputs represent. For example, if you're collecting shipping information, you already ask for information in structured fields. Structured search is primarily designed for address searches and can interpolate house numbers for new addresses not in our datasets.\n\n**Search** is similar to autocomplete: it takes natural-language input as a single string, but assumes the input is reasonably complete. **Search** can be used in non-search-as-you-type UIs or integrated with **autocomplete** when the user presses enter or clicks a search button. Like structured geocoding, search can interpolate house numbers that aren't in our datasets.\n\n## Checkout Forms: A Practical Example\n\nLet's look at a common example we're often asked about: collecting billing and shipping addresses in checkout forms. Which endpoint to choose? As with most decisions, it's a trade-off. The main question is what UX you think is best for your users. The forward geocoding endpoints are here to support your desired flow.\n\nThe classic checkout form has structured fields like \"street\", \"city,\" and \"state.\" This is the most common style for a reason. Your logistics provider and payments processor probably already expect data in this form, and it's fairly familiar to users by this point. This is a clear fit for structured geocoding. Most of your fields will map clearly to a structured geocoding parameter, so validating the address is easy. It doesn't validate as you type, but it has a very high hit rate, even for new addresses not yet in our datasets.\n\nAn alternative approach that's gaining popularity is to have a single autocomplete search box as the initial UX, then expand to the structured form after the user selects an address. This is typically easier and faster for the users, but search-as-you-type comes with the trade-off of not supporting interpolation, so you'll probably need to combine this with **search**.\n\nWhichever route you take, our geocoding APIs both return detailed structured components, so you can build whichever UX you like. You can also show this on a map for the user to validate, reducing the chances of a failed delivery.\n\n## Alternate \u002F Hybrid Flows: A Case Study of Korean Address Entry\n\nIf you're focused on a smaller geographic area or building for other use cases like vehicle navigation, you might consider hybrid approaches for a better user experience. For example, in South Korea, it's common to have buttons (in cars) or a drop-down menu selection (web or mobile) to \"drill down\" the hierarchy.\n\nIn a narrowly focused integration, you can even skip the country and start with a limited menu of administrative divisions. Presenting the user with just a few options speeds up the address selection process. For example, selecting Seoul and then Gangseo-gu. You can then pass this filtered context off to any of our forward geocoding endpoints to give the user a faster and more accurate search experience.\n\n## What's Next\n\nNo product is perfect, and we don't stop building! We've got some exciting improvements in the works, including an improved geocoding API v2, a \"nearby\" category-based POI search, and support for autocomplete interpolation.\n\nIf you have any questions that this post or our [docs](https:\u002F\u002Fdocs.stadiamaps.com\u002Fgeocoding-search-autocomplete\u002Foverview\u002F) didn't cover, get in touch with [our world-class support team](mailto\\:support@stadiamaps.com). We'd love to hear from you!\n",{"id":255,"bio":256,"extension":18,"jobTitle":257,"meta":258,"name":259,"sameAs":260,"slug":28,"stem":262,"twitterCreator":263,"type":27,"url":27,"__hash__":264},"authors\u002Fauthors\u002Fian-wagner.yml","Ian is co-founder of Stadia Maps and leads engineering and operations. He works on routing, navigation, and the technical foundations that keep customer applications reliable at scale.","Founder & Chief Architect",{},"Ian Wagner",[261],"https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fian-w-wagner\u002F","authors\u002Fian-wagner","@ianthetechie","TXFYOIHMojwkwBmlep16sDSvJARwPKVf_-PvaouYKwI",1789405582627]