Table of Contents

Preparing offline maps for Mapeo Desktop and Mapeo Mobile from Mapbox Studio

This workflow is for downloading map styles and tiles from Mapbox Studio to get these working offline in Mapeo Desktop Observations and Mapeo Mobile.

mapbox-style-downloader is a Node script created by Digital Democracy which can download Mapbox styles, sprites, glyphs (fonts) and tiles for offline usage.

<aside> ❗ Note: Mapbox is currently requesting that all third parties using this script ask for permission from the community team before using. If you want to use this script, email [email protected] before proceeding.

Also, be careful: This has the capability to send Mapbox a lot of requests. Try not to get your token throttled beyond the free tier, resulting in a need to pay for your tile requests! Make sure you pick reasonable bounding boxes and zoom levels, because the data can get very large, very fast.

Refer to the pricing schema here; currently, maximum tile requests within the free tier to the Vector Tiles API is 200,000, and Raster Tiles API is 750,000.

</aside>

Install / setup Node and mapbox-style-downloader

1. Install Node (default version 12) on your computer.
2. Install the Node package mapbox-style-downloader by running npm install --global mapbox-style-downloader.

Download map style and tiles from Mapbox.com

1. Design a map on mapbox.com using Studio. Save your changes by Publishing the map.

   1. Note that it is possible to add raster imagery (such as satellite images) to Mapbox Studio i.e. in GeoTIFF format, and download it using the mapbox-style-downloader script.

   2. Before publishing the map, you need to set compatibility for Maps SDK for Android to 5.2.0+ and Mapbox GL JS to 1.4.0+.

      

2. Get your Mapbox map link and style token. On your Mapbox.com map, click on Share... and copy down the Style URL and Access token.

3. Get your bounding box for the tiles you will download, and calculate an estimate of the number of raster and vector tiles to be generated in advance. You can use the Mapbox tool for that: https://docs.mapbox.com/playground/offline-estimator/. Note that the maximum monthly tile requests to the Vector Tiles API is 200,000, and Raster Tiles API is 750,000.

   1. You can also use http://boundingbox.klokantech.com/, or QGIS to get coordinates.

4. Next, in the terminal navigate to a directory where you want to create the tiles.

   Tip: you can enter cd and then drag the directory from Finder or Explorer to the terminal to autogenerate the path.

5. Run the following line of code. You can use this script below as a model, and change the bits in bold as follows.

   mapbox-style download **-z 0 -Z 15** --bounds '**-123.105109,49.26913,-123.066898,49.290328**' **mapbox://styles/mapboxuser/dsfjl32r2ljflk23** --token='**pk.eysdjflsd2390jklsdf2sj490sjd92.sdjdildj29s**' -o '**curacao**' **-u 0 -U 9215 --asar**
   

   • -z 0 -Z 15 here put the minimum and maximum zoom levels you want. Generally, we keep the minimum one 0 so that a map of whole world appears and you zoom in gradually to area you want (the low zoom levels take up very little space, only from 14 upwards do they start taking up much space; each subsequent zoom level x4 the amount of space of previous level). If you are not building from raster styles, then there is no point going beyond 16. If you have raster tiles, then you may want to go further.
     • Tip: Depending on your maps and use case, there may be an optimal maximum Zoom level for you to use. This page from OpenStreetMap serves as handy guide for determining your zoom levels. https://wiki.openstreetmap.org/wiki/Zoom_levels
   • **-123.105109,49.26913,-123.066898,49.290328**Here you put in the bounds that you compiled above in step 3. They need to be in this order: W, S, E, N.
   • mapbox://styles/mapboxuser/dsfjl32r2ljflk23 Here is where you put your own map style URL that you compiled in step 2.
   • pk.eysdjflsd2390jklsdf2sj490sjd92.sdjdildj29s here is where you put in your own Mapbox token, compiled in step 2.
   • curacao. This is the name of the folder where the offline map content will be downloaded.
   • -u 0 -U 9215 This is the character range which is downloaded with the style. This range allows for certain French characters we needed for Montreal and most French and Spanish characters. If we had areas with Chinese characters or languages with special characters then we might need the range to be different/bigger.
     • u 0 -U 9215, for example, is telling the script to download a subset of fonts, unicode 0-9215 (which is 23FF in hex). This may not include all the characters used in the map, for example numbers in a circle ① ② ③ are unicode 9314 so would not be included, and if a label were to use them then the map would crash. The safest thing to do is to leave off the u and U arguments and it will default to downloading the entire character set (0-65536).
   • --asar puts the tiles in a compressed format which both Mapeo Desktop Observations and Mapeo Mobile can read. Note: if you don't put the --asar parameter, the script will generate a directory of tiles which Mapeo Desktop Observations can use, but Mapeo Mobile cannot.

6. When successfully completed, the script will have generated a directory containing the following (unless you included a parameter to only download one of these):

   1. A style.json file with your tileset definitions, and map canvas.
   2. A tiles directory containing your map vector and raster tiles.
   3. A glyphs directory containing your font glyphs.
   4. A sprites directory containing graphics for icons used on your map.

• NOTE: With the mapbox-style-downloader script, all resources (style.json, glyphs, tiles, and sprites) are downloaded by default. However, it is possible to download only one of these elements by adding --style, --glyphs, --tiles, --sprites parameters to your script. This can be useful in case you only want to download the style, sprites, or fonts (glyphs), and don't need the tiles again. (The style.json is always downloaded, since it is needed to get the URLs for the other resources.) More on this in the documentation on Github.

  Important to note is that if you use this script to only download the style.json file, it will not reference local tiles in the sources and that will have to be changed manually.