Metadata-Version: 2.4
Name: mapillary_downloader
Version: 0.4.2
Summary: Download your Mapillary data before it's gone
Author-email: Gareth Davidson <gaz@bitplane.net>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: License :: Public Domain
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
License-File: LICENSE.md
Requires-Dist: requests>=2.31.0
Requires-Dist: piexif>=1.1.3
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: pytest ; extra == "dev"
Requires-Dist: coverage ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: build ; extra == "dev"
Requires-Dist: twine ; extra == "dev"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: pydoc-markdown ; extra == "dev"
Requires-Dist: Pillow ; extra == "dev"
Project-URL: Documentation, https://bitplane.net/dev/python/mapillary_downloader/pydoc
Project-URL: Homepage, https://bitplane.net/dev/python/mapillary_downloader
Project-URL: Issues, https://github.com/bitplane/mapillary_downloader/issues
Project-URL: Repository, https://github.com/bitplane/mapillary_downloader
Provides-Extra: dev

# 🗺️ Mapillary Downloader

Download your Mapillary data before it's gone.

## Installation

Installation is optional, you can prefix the command with `uvx` or `pipx` to
download and run it. Or if you're oldskool you can do:

```bash
pip install mapillary-downloader
```

## Usage

First, get your Mapillary API access token from
[the developer dashboard](https://www.mapillary.com/dashboard/developers)

```bash
# Set token via environment variable (recommended)
export MAPILLARY_TOKEN=YOUR_TOKEN
mapillary-downloader USERNAME1 USERNAME2 USERNAME3

# Or pass token directly, and have it in your shell history 💩👀
mapillary-downloader --token YOUR_TOKEN USERNAME1 USERNAME2

# Download to specific directory
mapillary-downloader --output ./downloads USERNAME1
```

| option          | because                                      | default            |
| --------------- | -------------------------------------------- | ------------------ |
| `usernames`     | One or more Mapillary usernames              | (required)         |
| `--token`       | Mapillary API token (or env var)             | `$MAPILLARY_TOKEN` |
| `--output`      | Output directory                             | `./mapillary_data` |
| `--quality`     | 256, 1024, 2048 or original                  | `original`         |
| `--bbox`        | `west,south,east,north`                      | `None`             |
| `--no-webp`     | Don't convert to WebP                        | `False`            |
| `--workers`     | Number of parallel download workers          | Half of CPU count  |
| `--no-tar`      | Don't tar sequence directories               | `False`            |
| `--no-check-ia` | Don't check if exists on Internet Archive    | `False`            |

The downloader will:

* 🏛️ Check Internet Archive to avoid duplicate downloads
* 📷 Download multiple users' images organized by sequence
* 📜 Inject EXIF metadata (GPS coordinates, camera info, timestamps,
  compass direction)
* 🗜️ Convert to WebP (by default) to save ~70% disk space
* 🛟 Save progress so you can safely resume if interrupted
* 📦 Tar sequence directories (by default) for faster uploads to Internet Archive

## WebP Conversion

You'll need the `cwebp` binary installed:

```bash
# Debian/Ubuntu
sudo apt install webp

# macOS
brew install webp
```

To disable WebP conversion and keep original JPEGs, use `--no-webp`:

```bash
mapillary-downloader --no-webp USERNAME
```

## Sequence Tarball Creation

By default, sequence directories are automatically tarred after download because
if they weren't, you'd spend more time setting up upload metadata than actually
uploading files to IA.

To keep individual files instead of creating tars, use the `--no-tar` flag.

## Internet Archive upload

I've written a bash tool to rip media then tag, queue, and upload to The
Internet Archive. The metadata is in the same format. If you symlink your
`./mapillary_data` dir to `rip`'s `4.ship` dir, they'll be queued for upload.

See inlay for details:

* [📀 rip](https://bitplane.net/dev/sh/rip)


## Development

```bash
make dev      # Setup dev environment
make test     # Run tests
make dist     # Build the distribution
make help     # See other make options
```

## Links

* [🏠 home](https://bitplane.net/dev/python/mapillary_downloader)
  * [📖 pydoc](https://bitplane.net/dev/python/mapillary_downloader/pydoc)
* [🐍 pypi](https://pypi.org/project/mapillary-downloader)
* [🐱 github](https://github.com/bitplane/mapillary_downloader)
* [📀 rip](https://bitplane.net/dev/sh/rip)

## License

WTFPL with one additional clause

1. Don't blame me

Do wtf you want, but don't blame me if it makes jokes about the size of your
disk drive.

