When adding custom data to a map, you may find that some of your data exist in a source that is separate from your geospatial data. For example, you might have a table of population data by country but the only spatial information included is the country name. In this case you need a way to ‘join’ the data to geometries, like country boundaries, to be able to visualize them on a map. In some cases, it can be tricky to prepare joined data before adding it to a map, for example, if the data are updating frequently, if the data file is large, or if you can’t directly edit the geometries source that you want to use (like a Mapbox Boundaries tileset).

Using a ‘client-side data-join’ lets you combine vector tile geometries with other data dynamically when your web map loads. In this tutorial, you will learn how to use the Feature State method to join a vector tile to an external data file, and then use data-driven style notation to visualize the data.

Access the tutorial and template code here.

View our finished example map at https://labs.mapbox.com/impact-tools/data-joins/.

Need more help? Ask questions on Stack Overflow or contact Mapbox Support. If you are working on a social good project, contact the Mapbox Community Team.

Want to share what you’ve built? Tweet it with #builtwithmapbox

‍