Back to the README.
The estimated download size is calculated from the images you have already downloaded, in this order of preference:
The camera model and image size are known from the Mapillary API before the download. Up to 200 downloaded images per camera model and year in the selected date range are used. If there are not enough, up to 100 images per camera model from the rest of the backup folder are read, newest first. For an empty backup folder 2.5 MB per image is used.
The download time assumes 90% of the network speed; the remaining 10% account for protocol overhead, API requests and waiting for the disk.
The HTTP requests line counts the requests to the Mapillary API and the image
downloads. Failures include network errors, HTTP errors (e.g. an expired image
URL) and incomplete or broken images. Failed requests are retried; the line says
whether all of them were retried successfully, or what was given up after all
retries and is missing in this run, e.g.
(17 failed, given up: 1 search time window, 12 images). Run the script
again later to download the missing images.
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
Images which were downloaded with the other layout are recognized and not downloaded again, so you can switch between both layouts at any time.
With --fallback-2048, images which Mapillary doesn't have in original size are
stored as <captured_at>_<sequence_id>_NNNN_2048.jpg (2048 px). They count as
downloaded in the next runs, also without --fallback-2048.
During a download the output folder contains the lock file
.mapillary-takeout.lock (with the process id), so a second run for the same
folder, e.g. a cron job which starts while the last one is still running,
exits with status 75. The lock is released when the script ends, also after
a crash or kill -9; the empty file stays. This works on Linux, macOS and
FreeBSD. On a drive without file locks (some SMB/NFS network drives,
exFAT/FAT USB disks) the script prints a warning and runs without a lock.
Note: the file names differ from version 1.x, a backup made with version 1.x will not be recognized as already downloaded.
./mapillary-takeout-v4.py --help
usage: mapillary-takeout-v4.py [-h] [--version] [--token TOKEN] [--start-date YYYY-MM-DD]
[--end-date YYYY-MM-DD] [--last-days N] [--bbox W,S,E,N]
[--make MAKE] [--model MODEL] [--list-cameras] [--debug 0..4]
[--timeout 1..300] [--timeout-meta 1..300] [--threads 1..128]
[--meta-threads 1..64] [--retries 0..512] [-D] [--subfolder]
[--no-subfolder] [--metadata] [--exif] [--no-exif]
[--exif-writer {auto,piexif,exiftool}] [--fallback-2048]
[--max-size SIZE] [--max-time TIME] [--disk-reserve SIZE]
[--no-disk-check] [--no-version-check] [--no-mtime]
username [output_folder]
Download your images from Mapillary (API v4), version: x.yy
Homepage: https://download.bbbike.org/src/mapillary-takeout-v4/
positional arguments:
username your Mapillary username
output_folder download destination (not needed for --list-cameras)
options:
-h, --help show this help message and exit
--version show the version and exit; with --debug 1 or higher (default) also whether
a newer version is available
--token TOKEN Mapillary access token (client token from
https://www.mapillary.com/dashboard/developers), default: $MAPILLARY_TOKEN
--start-date YYYY-MM-DD
only images captured on or after this date, default: 2013-01-01
--end-date YYYY-MM-DD
only images captured on or before this date (the end date is included)
--last-days N only images of the last N days: today and the N days before, e.g. --last-
days 14. Can't be combined with --start-date/--end-date
--bbox W,S,E,N limit the search to a bounding box (lon/lat)
--make, --manufacturer MAKE
only images of this camera manufacturer (EXIF "Make"), e.g. Apple, GoPro
(case-insensitive substring)
--model MODEL only images of this camera model (EXIF "Model"), e.g. iPhone (case-
insensitive substring)
--list-cameras list the cameras (make/model) with the number of images and exit
--debug 0..4 set the debug level, default: 1
--timeout 1..300 connection/read timeout for image downloads in seconds, default: 10
--timeout-meta 1..300
connection/read timeout for metadata requests in seconds, default: 60
--threads 1..128 number of parallel image downloads, default: 16
--meta-threads 1..64 number of parallel metadata requests (search, image URLs), default: 32
--retries 0..512 max. retries of a sequence if no image could be downloaded, with
increasing wait time, default: 8
-D, --dry-run show what would be downloaded, with size and time estimates, and exit
--subfolder store images in a folder per day and a subfolder per sequence, default: on
--no-subfolder store images in a folder per day, without subfolders per sequence
--metadata store image metadata (GPS, compass, capture time) as .json, default: off
--exif write GPS position, capture time, compass angle and camera into the JPEG
(needs piexif or exiftool), default: on
--no-exif store the images as served by Mapillary, without EXIF
--exif-writer {auto,piexif,exiftool}
tool to write EXIF, auto: piexif if installed, else exiftool, default:
auto
--fallback-2048 images without original at Mapillary: download the 2048 px version as
<name>_2048.jpg, default: skip them with a warning
--max-size SIZE stop after downloading this much, e.g. 500M, 50G or 2T (default unit G);
the next run continues
--max-time TIME stop the run after this time, e.g. 90m, 12h or 2d (default unit h), also
the search; the next run continues
--disk-reserve SIZE free disk space to keep, on top of the estimated download size: a size
like 50G, 500M or 2T (default unit G), or a percentage of the download
size like 10%, default: 5%, at least 10.0 GB
--no-disk-check don't stop if the estimated download size is larger than the free disk
space
--no-version-check don't check at startup whether a newer version is available, also with
$MAPILLARY_TAKEOUT_NO_VERSION_CHECK=1
--no-mtime keep the download time as modification time of the images, default: set it
to the capture time
--meta-threads), the oldest
unfinished time window first: the parts of a full window are searched right
away, so the search moves forward by date. The progress line shows the date
up to which all images are found:
Found 713,904 images, complete up to 2019-03-01 ...
and a line for each month as soon as it is completely searched (months
without images are left out; UTC, like the search):
Aug 2026: 18,412 images in 97 sequences
Sep 2026: 23,046 images in 112 sequences
With a camera filter: Sep 2026: 23,046 images, 1,200 matching in 12 sequences.
A sequence across the end of a month is counted in both months.--last-days or --start-date for faster weekly runs.Progress: 2,304 of 761,015 images (0.3%), 15 of 1,117 sequences, about 10h 46m left, done ~ Thu 22:15Image lists: 7,340 of 18,558 sequences (40%) ...
Checking the backup folder: 18,558 of 18,558 sequences ...NNNN in the file names come from the image list of the
sequence on Mapillary (one request per sequence). If this list can't be
fetched, the sequence is skipped with a warning and downloaded in the next run.<captured_at> in the file names is the capture time of the first image of
the sequence. A sequence which started before the date range (e.g. a night
drive across midnight and --last-days) gets the same start time and file
names as in a run without a date range: the script asks for the capture time
of its first image (one request per such sequence). The whole sequence is
downloaded.--start-date is counted in the dry run only with its images
in the date range.There are two levels of retries: single HTTP requests, and complete download rounds of a sequence.
--threads). Failed images are retried in the next download round. If no
image of a sequence could be downloaded in a round (e.g. the network is
down), the script waits 5 seconds, doubles the wait time after each failed
round up to 5 minutes, and gives up the sequence after 8 failed rounds
(--retries), which bridges a network outage of about 15 minutes. A round
with at least one downloaded image does not count as failed.What happens with an image that can't be downloaded:
| Situation | Behavior |
|---|---|
| Temporary network or server error | Retried in the next round |
| Expired download URL (HTTP 403) | Fresh URL, retried right away |
| Not found on the server (HTTP 404, also with a fresh URL) | Skipped, reported per sequence, exit status 1 |
| No original size at Mapillary | Skipped with a warning, exit status not changed: it would fail in every run, and a weekly cron job would always report an error |
| No original size, but a 2048 px version | Downloaded as _2048.jpg with --fallback-2048, otherwise skipped with a warning |
The download URLs (thumb_original_url) are signed and expire after some time;
expired URLs are refreshed automatically.
At the end of a run a summary lists the images which were not downloaded, e.g.
No new images downloaded.
Not downloaded: 1,581 images not available at Mapillary in original size, 4 images not found on the Mapillary server (HTTP 404)
"You are up to date" is only shown if nothing was skipped.
--disk-reserve, e.g. --disk-reserve 50G
for a fixed size (K, M, G, T, default unit G), --disk-reserve 10% for a
share of the download size, or --disk-reserve 0.--no-disk-check turns this off.df). On macOS,
"purgeable" space which Finder counts as available is not included.--max-size the disk check only needs room for that much, e.g.
--max-size 50G fills a backup in steps on a disk which can't hold all
images yet.--max-size 50G stops the run after 50 GB downloaded (K, M, G, T, default
unit G), --max-time 8h after 8 hours (s, m, h, d, default unit h). The
time limit counts from the start of the run and covers the search, the image
lists and the check of the backup folder too, also for --dry-run and
--list-cameras.Stopped: --max-time 8h reached, 1,234 images downloaded (3.1 GB), about 5,678 left
and exits with status 1. The next run continues where this one stopped.--no-exif is given): DateTimeOriginal (UTC,
with OffsetTimeOriginal +00:00), SubSecTimeOriginal,
GPSLatitude/GPSLongitude, GPSAltitude, GPSImgDirection,
GPSDateStamp/GPSTimeStamp, Make, Model and ImageDescription
(Mapillary image and sequence id). The values recorded by your camera are
preferred, Mapillary's computed values are used as a fallback. Without piexif
or exiftool the images are stored without EXIF and a warning is printed.Orientation is not written: the images from Mapillary may already be
rotated, and a wrong value would turn them sideways.-stay_open mode for the whole download (about 10 ms per image),
so it does not slow down the download..json file) is set
to the capture time, so ls -lt and photo tools sort the images in the
order they were taken. Use --no-mtime to keep the download time.
Images which were downloaded before are not changed.--meta-threads). The images are downloaded with
16 threads (--threads).mapillary-takeout-v4/<version> (+https://download.bbbike.org/src/mapillary-takeout-v4/)
instead of the generic python-requests/<version>. --debug 2 shows it in
the settings.The tests need no network and no access token: a fake Mapillary API and a fake image CDN replace the HTTP requests. Run them from the top folder, one process per test file, in parallel on all CPUs:
python3 tests/run_tests.py
-v shows the name of every test, -j 4 limits the number of processes, and
test files can be given as arguments, e.g. python3 tests/run_tests.py test_search.py.
Without the runner the tests run one after another:
python3 -m unittest discover -s tests -v
They cover the image search (all images found, also with more than 2,000 images
per time window), date ranges, camera filter, both folder layouts, the dry run
and size estimate, retries and error handling, exit status, disk space check,
lock file, 2048 px fallback, --max-size and --max-time, the version check,
EXIF and the modification time. The EXIF tests
need piexif or exiftool, otherwise they are skipped. The tests need Python 3.7
or later.
| File | Tests |
|---|---|
takeout_helpers.py |
fake Mapillary API and image CDN, test images, base test cases |
test_search.py |
image search, date ranges, camera filter, progress and month lines |
test_download.py |
downloads, folder layouts, dry run |
test_errors.py |
errors, retries, exit status |
test_cli.py |
usage errors of the command line (runs the script) |
test_cli_output.py |
output, --help, --version, option aliases (runs the script) |
test_sequence_start.py |
sequences which started before the date range |
test_unattended.py |
disk space check, lock file, 2048 px fallback |
test_exif.py |
EXIF with piexif and exiftool |
test_estimate.py |
size estimate of the dry run |
test_storage.py |
compact storage of the search result |
test_format.py |
number, size and time formatting |
test_connections.py |
HTTP connection reuse with a local HTTP server |
test_version_check.py |
check for a newer version, with a local HTTP server |
test_limits.py |
--max-size and --max-time |
mapillary-takeout-v4.py, 2026) is a port to the Mapillary API
v4 (graph.mapillary.com). The API v4 has no list of a user's sequences, so
the search and the download were rewritten. It also offers no original
unprocessed images: the images are blurred, re-encoded and without EXIF, so
EXIF restoration was added.The file names changed: version 1.x used the capture and upload time, version 2.x uses the capture time and the sequence ID. A backup made with version 1.x is therefore not recognized as already downloaded.