mapillary-takeout-v4

Download your own Mapillary images in full resolution for a local backup. Supports incremental downloads, date and camera filters, EXIF restoration, a dry run with size and time estimates, and Docker.

Run it again at any time: already downloaded images are skipped automatically. This makes it suitable for regular backups, for example with a weekly cron job. The images are sorted by day and sequence.

Please note: images are downloaded at their original resolution, but they are not the original camera files: Mapillary applies privacy blurring (faces, license plates) and re-encodes them. The script restores the available metadata (GPS position, capture time, compass direction and camera) as EXIF tags. Keep the files from your camera as the real backup!

Contents

Requirements

(or use the Docker image, see Docker; for Windows see Windows)

System Install
Debian 12 or newer sudo apt-get install python3-requests python3-piexif
macOS brew install python3 && python3 -m pip install requests piexif
FreeBSD pkg install py311-requests p5-Image-ExifTool
others python3 -m pip install requests piexif

piexif is used if both piexif and ExifTool are installed, it is faster. If neither is installed, the images are downloaded without restored EXIF metadata and a warning is printed.

Access token

The API v4 does not support a login with email and password anymore. Instead you need an access token:

  1. Log in at https://www.mapillary.com/dashboard/developers
  2. Register an application (name and website can be anything, no special permissions needed)
  3. Copy the "Client Token", it starts with MLY|

Pass the token with --token or set the environment variable MAPILLARY_TOKEN.

Keep your access token private: do not commit it to Git, put it into scripts you share with others, or publish it in logs.

Installation

Download and unpack the latest version:

curl -O -sf https://download.bbbike.org/src/mapillary-takeout-v4/mapillary-takeout-v4-latest.tgz
tar xfv mapillary-takeout-v4-latest.tgz
cd mapillary-takeout-v4-*/

Quick start

export MAPILLARY_TOKEN='MLY|...'
./mapillary-takeout-v4.py your-mapillary-username /path/to/backup

You can run the script again at any time. Already downloaded images are skipped automatically.

The script is executable after unpacking. If your shell says Permission denied, run chmod +x mapillary-takeout-v4.py, or start it with python3 mapillary-takeout-v4.py.

Dry run

First, check what would be downloaded, with an estimate of size and time:

./mapillary-takeout-v4.py --dry-run your-mapillary-username /path/to/backup
mapillary-takeout-v4.py x.yy - download your images from Mapillary (API v4)
https://download.bbbike.org/src/mapillary-takeout-v4/
Settings:
...
takeout started at: Thu 29 Oct 2026 21:14:35 CET
2026-10-25 14:03Z  8f3kQ2pLx9...    600 images    1.7 GB  Apple iPhone SE (2nd generation)
2026-10-27 09:12Z  2m9xL7vTq1...    275 images (of 300)  770.0 MB  Apple iPhone SE (2nd generation)
875 images in 2 sequences to download, 25 already downloaded (all in subfolders)
Estimated download size: 2.5 GB (2.8 MB/image, based on 125 downloaded images)
Size estimate: 875 images by average size of the same camera model (in the same year, if possible)
Estimated download time: 2 Gbit/s: 11s, 1 Gbit/s: 22s, 500 Mbit/s: 44s, 250 Mbit/s: 1m 27s, 100 Mbit/s: 3m 38s, 50 Mbit/s: 7m 15s, 16 Mbit/s: 23m
Free disk space: 1.2 TB
HTTP requests: 1 search, 2 image lists (0 failed)
takeout ended at: Thu 29 Oct 2026 21:14:38 CET

With --debug 0 only the summary is shown:

./mapillary-takeout-v4.py --dry-run --debug 0 your-mapillary-username /path/to/backup
875 images in 2 sequences to download, 25 already downloaded (all in subfolders)
Estimated download size: 2.5 GB (2.8 MB/image, based on 125 downloaded images)
Estimated download time: 2 Gbit/s: 11s, 1 Gbit/s: 22s, 500 Mbit/s: 44s, 250 Mbit/s: 1m 27s, 100 Mbit/s: 3m 38s, 50 Mbit/s: 7m 15s, 16 Mbit/s: 23m

How the size is estimated and what the HTTP requests line means: see DETAILS.md.

Common options

Download only images captured in October 2026, including the metadata as a .json file next to each image:

./mapillary-takeout-v4.py --metadata --start-date 2026-10-01 --end-date 2026-10-31 your-mapillary-username '/path/to/MY BACKUP'

Both the start and the end date are included. The dates are in UTC.

Download only the images of the last 14 days: today and the 14 days before, 15 calendar days in total. This is useful for a weekly cron job: it also catches uploads which were processed late by Mapillary, and a missed run. With --debug 0 the script is quiet like other Unix tools: no progress, only errors and warnings, which go to stderr. So cron sends an email only if something went wrong:

./mapillary-takeout-v4.py --debug 0 --last-days 14 your-mapillary-username /path/to/backup

Limit a run, e.g. a cron job at night: --max-time 8h stops after 8 hours (also during the search), --max-size 50G after 50 GB downloaded. Downloads already running finish cleanly, the script exits with status 1 and the next run continues where this one stopped:

./mapillary-takeout-v4.py --max-time 8h --max-size 50G your-mapillary-username /path/to/backup

Store the images exactly as served by Mapillary, without writing EXIF:

./mapillary-takeout-v4.py --no-exif your-mapillary-username /path/to/backup

Filter images by camera

Show which cameras you used and how many images each has:

./mapillary-takeout-v4.py --list-cameras your-mapillary-username
    images  make                 model
     5,210  Apple                iPhone 13 Pro
     1,830  GoPro                HERO9 Black

Download only the iPhone pictures:

./mapillary-takeout-v4.py --model iphone your-mapillary-username /path/to/backup

--make is the camera manufacturer (also --manufacturer), --model the camera model, as shown by --list-cameras and stored in the EXIF tags Make and Model. Download only the GoPro pictures:

./mapillary-takeout-v4.py --make gopro your-mapillary-username /path/to/backup

--make and --model are case-insensitive substrings, so --model iphone matches "iPhone 13 Pro" as well as "iPhone 15". Images without camera information are listed as unknown.

Folder layout

Each sequence gets its own folder, below a folder for the day:

<output_folder>/<YYYY-MM-DD>/<captured_at>/<captured_at>_<sequence_id>_NNNN.jpg
<output_folder>/<YYYY-MM-DD>/<captured_at>/<captured_at>_<sequence_id>_NNNN.json   (with --metadata)

NNNN is the position of the image in the sequence, <captured_at> is the start time of the sequence. With --no-subfolder all images of a day are stored in the day folder:

<output_folder>/<YYYY-MM-DD>/<captured_at>_<sequence_id>_NNNN.jpg

Both layouts are recognized, see DETAILS.md for more.

Docker

The Dockerfile builds an image based on Debian 13 (trixie) slim with all packages the script needs: python3, requests, piexif, exiftool and tzdata.

Build the image:

docker build -t mapillary-takeout .

Download into the folder backup in the current directory:

mkdir -p backup
export MAPILLARY_TOKEN='MLY|...'
docker run --rm -e MAPILLARY_TOKEN --user "$(id -u):$(id -g)" \
    -v "$PWD/backup:/backup" mapillary-takeout your-mapillary-username /backup

All options work as usual, e.g. the last 14 days in local time:

docker run --rm -e MAPILLARY_TOKEN -e TZ=Europe/Berlin --user "$(id -u):$(id -g)" \
    -v "$PWD/backup:/backup" mapillary-takeout --last-days 14 your-mapillary-username /backup

Windows

The script is not tested on Windows. The easiest way is to run it like on Linux, in WSL (Debian or Ubuntu) or with Docker Desktop.

It should also work with Python for Windows:

python -m pip install requests piexif

Set the token in cmd (the quotes are needed because of the |):

set "MAPILLARY_TOKEN=MLY|..."
python mapillary-takeout-v4.py your-mapillary-username D:\mapillary-backup

or in PowerShell:

$env:MAPILLARY_TOKEN = 'MLY|...'
python mapillary-takeout-v4.py your-mapillary-username D:\mapillary-backup

Differences from Linux and macOS: * Windows does not allow : in file names, the times in the file and folder names are written as 10_00_00 instead of 10:00:00. A backup made on Windows is not recognized on Linux or macOS and the other way round, all images would be downloaded again. WSL and Docker use the Linux names. * There is no lock file, two runs at the same time for the same folder are not prevented.

Exit status

Exit status Meaning
0 all images downloaded, or nothing to do
1 errors during the download, some images are missing, or --max-size/--max-time reached (run the script again later)
2 invalid options or usage, e.g. a wrong date or a missing access token
3 authentication or API error, nothing could be downloaded
75 another run is already downloading into the output folder (EX_TEMPFAIL, like lockf -t 0)
130 interrupted with Ctrl-C (run the script again to continue)

A date range without any images (e.g. --last-days 1 on a day without uploads) is not an error.

Troubleshooting

Problem What to do
Authentication failed (exit 3) Check the token, see Access token. In Docker see the note on -e MAPILLARY_TOKEN in Docker.
The API refuses to search without a bounding box Add the area where you took your pictures, e.g. Berlin: --bbox 13.0,52.3,13.8,52.7
neither the Python module piexif nor exiftool was found Install piexif or exiftool, see Requirements, or use --no-exif.
Not enough disk space Free some space, download a shorter date range, or see --disk-reserve in DETAILS.md.
Another mapillary-takeout is already running (exit 75) A run for the same folder is still going, see the lock file in DETAILS.md.
not available at Mapillary in original size Mapillary has no original for these images, --fallback-2048 downloads the 2048 px version.
Some images missing (exit 1) Run the script again later, it downloads only what is missing.
Stopped: --max-time 8h reached (exit 1) The run stopped at the limit you set, see Common options. The next run continues.

More details

DETAILS.md has the size estimate, the full folder layout, how the script works (search, retries, disk space check, EXIF, memory), the full list of options and how to run the tests. ./mapillary-takeout-v4.py --help shows all options.

Versions

Check which version you have:

./mapillary-takeout-v4.py --version

At startup the script checks in the background whether a newer version is available, and shows a note at the end of the run:

A newer version 2.80 is available (you have 2.71):
https://download.bbbike.org/src/mapillary-takeout-v4/

--version checks too: it prints the version number alone on stdout (for scripts), and the note about a newer version on stderr.

The check asks download.bbbike.org for the latest version number, so the server sees your IP address. It never delays or stops a backup, and it shows nothing with --debug 0 (cron jobs). Turn it off with --no-version-check or the environment variable MAPILLARY_TAKEOUT_NO_VERSION_CHECK=1 (e.g. in Docker with -e MAPILLARY_TAKEOUT_NO_VERSION_CHECK=1).

Version 2.x uses the Mapillary API v4 (graph.mapillary.com). Version 1.x was written for the old API v3 on the Amazon AWS infrastructure, which Mapillary shut down in June 2021. See the history.

Contact

Homepage: https://download.bbbike.org/src/mapillary-takeout-v4/

General questions about Mapillary (your account, uploads, the Mapillary apps or the API itself) are better discussed in the Mapillary forum: https://forum.mapillary.com/

Questions, bug reports and ideas: Wolfram Schneider wosch@FreeBSD.org

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details