Metadata-Version: 2.4
Name: mapillary-dl
Version: 0.1.5
Summary: CLI tool to bulk-download street-level imagery from Mapillary
Author: Stiven
License-Expression: MIT
Project-URL: Homepage, https://github.com/SomeoneElseSt/mapillary-dl
Project-URL: Contact, https://stiven.me
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: folium>=0.17
Requires-Dist: mapillary>=1.0
Requires-Dist: piexif>=1.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: questionary>=2.0
Requires-Dist: requests>=2.31
Requires-Dist: tqdm>=4.66
Dynamic: license-file

# mapillary-dl

CLI tool to bulk-download street-level imagery from [Mapillary](https://www.mapillary.com/). Define a bounding box or pick a city, and it discovers and downloads every available image — with GPS embedded in EXIF, resumable downloads, and a SQLite cache that makes re-runs instant.

> This tool was spun off from [CityZero](https://github.com/SomeoneElseSt/CityZero/tree/master/mapillary), where its original commit history can be found.

## Install

```bash
pip install mapillary-dl
```

## Setup

Get a client token from [mapillary.com/dashboard/developers](https://www.mapillary.com/dashboard/developers) and export it:

```bash
export MAPILLARY_CLIENT_TOKEN=MLY|...
```

## Usage

```bash
# Interactive mode — pick a city, then download
mapillary-dl

# Specify a city directly
mapillary-dl --city "San Francisco"

# Custom bounding box
mapillary-dl --bbox "-122.52,37.70,-122.35,37.83"

# Limit images (useful for testing)
mapillary-dl --city "New York" --limit 100

# Show available cities
mapillary-dl --list-cities
```

## Options

| Option | Description |
|--------|-------------|
| `--city NAME` | Download from a predefined city |
| `--bbox W,S,E,N` | Custom bounding box |
| `--limit N` | Cap the number of images to download |
| `--output-dir PATH` | Output directory (default: `<city>` or `bbox#` in current directory) |
| `--preview` | Open an interactive map in the browser before downloading |
| `--state STATE` | Resume behaviour: `maintain` \| `merge` \| `rediscover` |
| `--granularity 1-100` | Discovery thoroughness (default: 25) |
| `--list-cities` | Show predefined cities and exit |

## Discovery states

When a previous run exists for a city:

| State | Behaviour |
|-------|-----------|
| `maintain` | Load from cache, skip API (default) |
| `merge` | Re-discover and add new images to existing cache |
| `rediscover` | Wipe cache and run a full fresh discovery |
