Map Tile Downloader

January 31, 2026 · View on GitHub

This Python script downloads map tiles from Thunderforest's Mobile Atlas for specified regions at multiple zoom levels. It supports resuming downloads by skipping already downloaded files and provides a progress bar to track the download progress. This was designed to make map tiles that are compatible with the Lilygo T-Deck running Ripple.

Features

Download map tiles from Thunderforest's Mobile Atlas
Specify multiple regions and zoom levels
Skip already downloaded files
Progress bar to track download progress
New utility (KMLtoTiles.py) supports gross parsing of a KML, then fetching tiles at waypoints and routes

Requirements

Python 3.x
requests library
tqdm library
dotenv library
For KMLtoTiles: fastkml library

Installation

Clone the repository:

git clone https://github.com/fistulareffigy/MTD-Script.git
cd MTD-Script

Install the required Python packages:
```
pip install -r requirements.txt
```
Note: fastkml is not required to use TileDL.py

Configuration

Obtain an API key from Thunderforest.

copy .env_sample as .env and edit it to include your API key, desired regions, max workers, and zoom levels:

API_KEY="your_api_key_here"
REGIONS="southern_ontario:41.5, -83.5, 45.5, -75.0;
las_vegas:35.5, -116.0, 37.5, -114.0;
grand_canyon:35.5, -113.0, 37.0, -111.0"
WORKERS=10
MINZOOM=1
MAXZOOM=14

Choose map style

# mapstyle = "cycle"
# mapstyle = "transport"
# mapstyle = "landscape"
# mapstyle = "outdoors"
# mapstyle = "transport-dark"
# mapstyle = "spinal-map"
# mapstyle = "pioneer"
mapstyle = "mobile-atlas"
# mapstyle = "neighbourhood"
# mapstyle = "atlas"

Usage (TileDL.py)

The tiles will be saved in a folder named tiles on your desktop, organized by zoom level and tile coordinates.

Run the script to start downloading tiles:

python TileDL.py

Usage (KMLtoTiles.py)

Run the script to start downloading tiles:

python KMLtoTiles.py <kmlfile> -k your_api_key_here -o ~/map -s outdoors -m 1000

KMLtoTiles.py [-h]
	      [-k APIKEY]
              [-s {outdoors,mobile-atlas,cycle,transport,landscape,transport-dark,spinal-map,pioneer,neighbourhood,atlas}]
	      [-m MAXTILES] [-o OUTDIR] [--minzoom MINZOOM] [--maxzoom MAXZOOM] [--latrgn LATRGN] [--lonrgn LONRGN]
	      kmlfile

Process KML file into selected tiles

positional arguments:
  kmlfile

optional arguments:
  -h, --help            show this help message and exit
  -k APIKEY, --apikey APIKEY
  -s {outdoors,mobile-atlas,cycle,transport,landscape,transport-dark,spinal-map,pioneer,neighbourhood,atlas}, --style {outdoors,mobile-atlas,cycle,transport,landscape,transport-dark,spinal-map,pioneer,neighbourhood,atlas}
  -m MAXTILES, --maxtiles MAXTILES
  -o OUTDIR, --outdir OUTDIR
                        output directory (default: /home/ghn/maps)
  --minzoom MINZOOM     minimum zoom level
  --maxzoom MAXZOOM     maximum zoom level
  --latrgn LATRGN
  --lonrgn LONRGN

The map projection used for tilings is EPSG:3857, sometimes called the "Web Mapping System." It is a variation of the Mercator Projection. It can be helpful to think of zoom levels as dividing the globe by powers-of-two. This is very straightforward for longitude, but more complex for latitude where the projection plays out.

Zoom Level	Deg Lon Per Tile	DMS Lon Per Tile	Width of Tile at 45°N
1	180.00	180°00'00"	10001km
2	90.00	90°00'00"	6667km
3	45.00	45°00'00"	3501km
4	22.50	22°30'00"	1768km
5	11.25	11°15'00"	886km
6	5.63	5°37'30"	443km
7	2.81	2°48'45"	222km
8	1.41	1°24'23"	111km
9	0.70	0°42'11"	5544m
10	0.35	0°21'06"	2772m
11	0.18	0°10'28"	1386m
12	0.09	0°05'16"	693m
13	0.04	0°02'38"	346m
14	0.02	0°01'19"	173m
15	0.01	0°00'40"	87m