streetview-dl 0.7.0

Download high-resolution Google Street View panoramas from the command line

streetview-dl

Extract, analyze, and download Google Street View panoramas at scale.

What it does

Converts Google Maps Street View URLs into full-resolution equirectangular panorama images. Downloads the raw tiles from Google's official Map Tiles API and stitches them together, preserving maximum quality and adding proper 360° metadata.

New: Discover and download historical Street View imagery! The tool can automatically find and download multiple time periods for locations with historical captures, perfect for documenting changes over time.

For example, the 6th Street Bridge in Los Angeles:

More: See the tool in action with these examples or read a Medium post about it.

Installation

# From PyPI
pip install streetview-dl

# From source
git clone https://github.com/yourusername/streetview-dl
cd streetview-dl
pip install -e .

Quick start

Download from URL

# Basic download
streetview-dl "https://www.google.com/maps/@33.99,-118.40,3a,75y,148h,98t/..."

# Specify output file
streetview-dl --output beach-pano.jpg "https://maps.url..."

# Lower quality for smaller files
streetview-dl --quality medium "https://maps.url..."

# Black and white filter
streetview-dl --filter bw "https://maps.url..."

Query by coordinates

Discover Street View panoramas at any location without needing a URL:

# Find nearest panorama (auto-generates URL file for downloads)
streetview-dl query --lat 34.05 --lng -118.25

# Search wider area with multiple results
streetview-dl query --lat 34.05 --lng -118.25 --radius 100 --max-results 10

# Batch download using auto-generated URL file
streetview-dl --batch streetview_urls_34.05_-118.25.txt --output-dir ./panoramas/

# JSON output for custom scripting (no URL file created)
streetview-dl query --lat 34.05 --lng -118.25 --json

Real example - Alcatraz Island (27 acres):

# Comprehensive discovery with deep traversal
streetview-dl query --lat 37.8267028 --lng -122.4242763 --radius 100 --max-results 150 --depth 5

Discovers 150 panoramas from 2013-2014 within 28-209m of center in ~23 seconds. Automatically creates alcatraz_urls.txt for batch downloading.

This unlocks grid-based sampling, automation workflows, and programmatic Street View discovery.

Understanding Street View URLs

Google Maps Street View URLs contain parameters that determine the viewing perspective. Understanding these helps you use --fov and --clip options effectively.

Example URL breakdown:

https://www.google.com/maps/@34.1309317,-118.4732331,3a,75y,32.27h,103.53t/data=...
                              │          │            │  │   │      │
                              │          │            │  │   │      └─ Pitch/tilt angle
                              │          │            │  │   └─ Heading (yaw) in degrees  
                              │          │            │  └─ Field of view in degrees
                              │          │            └─ Street View mode token
                              │          └─ Longitude
                              └─ Latitude

Key parameters for image processing:

• 32.27h - Heading/Yaw (32.27°): Compass direction the camera faces

  • 0°/360° = North, 90° = East, 180° = South, 270° = West
  • Used by --clip left|right to determine forward/rear direction

• 75y - Field of View (75°): How much the camera "sees" horizontally

  • Smaller values = zoomed in, larger = zoomed out
  • Note: URL FOV is different from --fov - URL FOV is the original view, --fov crops the downloaded panorama

• 103.53t - Pitch/Tilt (103.53°): Up/down angle of camera

  • Lower values look up, higher values look down
  • Affects what you see when using --crop-bottom

How URL parameters relate to options:

# URL shows heading 32° - clip to forward-facing 180°
streetview-dl --clip right "https://maps.url.../32.27h/..."

# URL shows heading 32° - clip to rear-facing 180° (32° + 180° = 212°)  
streetview-dl --clip left "https://maps.url.../32.27h/..."

# Crop 120° around the URL's heading direction (32°)
streetview-dl --fov 120 "https://maps.url.../32.27h/..."

# Combine: 200° crop in the forward direction from URL heading
streetview-dl --fov 200 --clip right "https://maps.url.../32.27h/..."

Setup

Get a Google Maps API key

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the "Map Tiles API"
4. Create credentials → API Key
5. Set up billing (required for Map Tiles API)

Configure authentication

Choose one method:

# Environment variable (recommended)
export GOOGLE_MAPS_API_KEY="your_api_key_here"

# CLI argument
streetview-dl --api-key "your_key" "https://maps.url..."

# Config file
streetview-dl --configure

Options

Quality and output

--quality high|medium|low    # Default: medium (8K resolution, good balance)
--output filename.jpg        # Custom output filename
--format jpg|png|webp        # Image format (default: jpg)
--jpeg-quality 85            # JPEG compression (1-100)
--max-width 8192             # Resize if larger

Coordinate query options

--lat LATITUDE               # Latitude (required for query command)
--lng LONGITUDE              # Longitude (required for query command)
--radius METERS              # Search radius in meters (default: 50)
--max-results N              # Maximum panoramas to return (default: 5)
--depth 1-5                  # Link traversal depth (auto-tuned if not set)
--max-panos N                # Maximum API calls during discovery (default: 200)
--json                       # Output as JSON (query command only)

Image processing

--fov 180                    # Field of view in degrees (60-360, crops around viewing direction)
--filter bw|sepia|vintage    # Apply artistic filters
--brightness 1.2             # Adjust brightness
--contrast 1.1               # Adjust contrast
--saturation 0.8             # Adjust color saturation
--clip left|right|none       # Clip to 180° half relative to view yaw (overrides FOV if < 180°)
--crop-bottom 0.75           # Keep top fraction of height (default: 0.75 to remove car blur)
--no-crop                    # Disable default bottom cropping (keep full image)

Metadata and batch processing

--metadata                   # Save metadata as JSON
--metadata-only              # Extract metadata without downloading
--historical                 # Discover and list historical imagery dates for this location
--historical-download        # Download all available historical images for this location
--historical-max-depth 7     # Search depth for historical discovery (1-10, default: 7)
--historical-max-panoramas 200  # Max panoramas to check (50-500, default: 200)
--batch urls.txt             # Process multiple URLs
--output-dir ./panoramas/    # Output directory for batch

Advanced

--no-xmp                     # Skip 360° metadata embedding
--timeout 30                 # Request timeout seconds
--retries 3                  # HTTP retry attempts
--backoff 0.5                # Retry backoff factor
--concurrency 0              # Parallel tile workers (0=auto by CPU/quality)
--configure                  # Configure API key interactively
--verbose                    # Verbose output

Usage

You can run the CLI on a single URL or a batch file.

streetview-dl 'https://www.google.com/maps/place/...'

Options of interest

• --accent-color [cyan|yellow]: changes terminal accent color
• --timeout SECONDS: request timeout (default 30)
• --retries N: HTTP retry attempts for transient errors (default 3)
• --backoff SECONDS: exponential backoff factor between retries (default 0.5)

Examples

Basic usage

# Download full resolution panorama
streetview-dl "https://www.google.com/maps/@40.7589,-73.9851,3a,75y,200h,90t/data=..."

Quality options

# High quality for maximum detail (16K resolution, ~10MB)
streetview-dl --quality high "https://maps.url..."

# Default medium quality (8K resolution, ~4MB, good balance)
streetview-dl "https://maps.url..."

# Low quality for thumbnails (4K resolution, ~1MB)
streetview-dl --quality low "https://maps.url..."

Field of view examples

# Narrow 90° view for architectural details
streetview-dl --fov 90 "https://maps.url..."

# Standard 180° half-panorama
streetview-dl --fov 180 "https://maps.url..."

# Wide 270° view for context
streetview-dl --fov 270 "https://maps.url..."

# Combine with quality for detailed crops
streetview-dl --quality high --fov 120 "https://maps.url..."

Artistic filters

# Black and white
streetview-dl --filter bw "https://maps.url..."

# Vintage sepia tone
streetview-dl --filter sepia --brightness 1.1 --contrast 0.9 "https://maps.url..."

Framing and cropping

# Basic download (automatically removes bottom 25% car blur)
streetview-dl "https://maps.url..."

# Crop to specific field of view around the viewing direction
streetview-dl --fov 180 "https://maps.url..."

# Clip to forward-facing 180° half (ignores --fov if smaller than 180°)
streetview-dl --clip right "https://maps.url..."

# Clip to rear-facing 180° half
streetview-dl --clip left "https://maps.url..."

# Combine FOV cropping with directional clipping (FOV should be ≥ 180°)
streetview-dl --fov 220 --clip right "https://maps.url..."

# Keep full image height (disable default car blur removal)
streetview-dl --no-crop "https://maps.url..."

# Custom bottom crop (more aggressive than default)
streetview-dl --crop-bottom 0.6 "https://maps.url..."

# Combine all framing options
streetview-dl --fov 200 --clip right --crop-bottom 0.8 "https://maps.url..."

💡 Want to see examples? Check out EXAMPLES.md for comprehensive CLI usage examples, or run python generate_examples.py to create sample outputs.

Batch processing

# Create urls.txt with one URL per line, then:
streetview-dl --batch urls.txt --output-dir ./panoramas/

Metadata extraction

# Get comprehensive metadata including camera orientation, address, and more
streetview-dl --metadata-only "https://maps.url..."

# Save both image and metadata
streetview-dl --metadata "https://maps.url..."

Query by coordinates

The query command discovers Street View panoramas at any location using lat/lng coordinates. This enables grid-based sampling, automation, and discovery without requiring URLs.

# Find nearest panorama (auto-generates URL file)
streetview-dl query --lat 34.05 --lng -118.25

# Search wider area with more results
streetview-dl query --lat 34.05 --lng -118.25 --radius 100 --max-results 10

# Download using auto-generated URL file
streetview-dl --batch streetview_urls_34.05_-118.25.txt --output-dir ./panoramas/

# JSON output for custom scripting (no URL file created)
streetview-dl query --lat 34.05 --lng -118.25 --json

Output includes:

• pano_id - Unique panorama identifier
• date - Capture date (YYYY-MM format)
• lat, lng - Actual panorama coordinates
• distance_m - Distance from query point in meters
• heading - Compass direction in degrees
• Auto-generated URL file for batch downloads (unless --json is used)

Options:

• --radius - Search radius in meters (default: 50)
• --max-results - Maximum panoramas to return (default: 5)
• --depth - Link traversal depth, 1-5 (auto if not set)
• --max-panos - Maximum API calls during discovery (default: 200)
• --json - Output as JSON for automation
• --verbose - Show detailed progress

Use cases:

• Create systematic grids for area coverage
• Sample panoramas along routes or boundaries
• Automate Street View data collection
• Build datasets for computer vision or mapping projects
• Find coverage in specific areas programmatically

Streamlined workflow:

# Query generates both JSON and a ready-to-use URL file
streetview-dl query --lat 34.05 --lng -118.25 --max-results 10

# Batch download using the auto-generated URL file
streetview-dl --batch streetview_urls_34.05_-118.25.txt --output-dir ./panoramas/

JSON output for scripting:

# Query with JSON output (no URL file created)
streetview-dl query --lat 34.05 --lng -118.25 --max-results 10 --json > panoramas.json

# Extract URLs and download
cat panoramas.json | jq -r '.panoramas[] | 
  "https://www.google.com/maps/@\(.lat),\(.lng),3a,75y,0h,90t/data=!3m7!1e1!3m5!1s\(.pano_id)!"' > urls.txt

streetview-dl --batch urls.txt --output-dir ./panoramas/

Python examples: See examples/query_example.py for a simple query → download workflow, examples/grid_coverage.py for systematic grid-based area sampling, and examples/alcatraz_example.py for a real-world case study.

Available metadata fields

The --metadata and --metadata-only flags extract comprehensive information from Google's Street View Tile API:

Location & Coordinates:

• lat, lng - Current panorama coordinates
• original_lat, original_lng - Original capture coordinates
• original_elevation_above_egm96 - Original elevation in meters

Camera Orientation:

• heading - Compass direction (0-360°)
• tilt - Camera pitch angle
• roll - Camera roll rotation
• url_yaw, url_pitch - Viewing angles from URL
• url_fov - Field of view from URL (e.g., 75°)
• url_mode_token - Street View mode (e.g., "3a")
• url_date - Date from URL if present (YYYYMMDDTHHMMSS format)

Image Details:

• pano_id - Unique panorama identifier
• image_width, image_height - Full panorama dimensions
• tile_width, tile_height - Individual tile dimensions
• imagery_type - "indoor" or "outdoor"

Capture Information:

• date - Capture date (YYYY-MM format)
• copyright_info - Attribution text
• address_components - Structured address data
• links - Connected panoramas with headings
• report_problem_link - Problem reporting URL

Historical imagery discovery

streetview-dl can discover and download historical Street View imagery for locations that have multiple capture dates. The tool uses enhanced link traversal to find different time periods available at a location.

# Discover available historical dates for a location
streetview-dl --historical "https://maps.url..."

# Download all available historical panoramas for a location
streetview-dl --historical-download "https://maps.url..."

# More aggressive search (higher API usage but finds more dates)
streetview-dl --historical --historical-max-depth 10 --historical-max-panoramas 500 "https://maps.url..."

# Combine with other options for historical downloads
streetview-dl --historical-download --quality high --filter bw "https://maps.url..."

Advanced options:

• --historical-max-depth N: Search depth (1-10, default: 7) - higher finds more dates but slower
• --historical-max-panoramas N: Max panoramas to check (50-500, default: 200) - higher limit for thorough search

Example: The Karate Kid apartment

The South Seas Apartments in Reseda, CA (Daniel LaRusso's apartment from The Karate Kid) has multiple historical captures:

# Discover historical dates at this famous location
streetview-dl --historical "https://www.google.com/maps/place/South+Seas+Apartments/@34.2084337,-118.55223,3a,75y,1.07h,79.39t/data=!3m8!1e1!3m6!1s7Dpn21NUjyv7RcROh2qzng!2e0!5s20220901T000000..."

# Download all historical versions
streetview-dl --historical-download --quality medium "https://maps.url..."

This discovers and downloads panoramas from multiple time periods:

• 2022-09: Most recent capture
• 2021-03: Mid-pandemic view
• 2018-05: Earlier historical view

See examples/historical-karate-kid-apartment/ for the actual downloaded images.

Limitations

Important: Historical discovery has inherent limitations due to Google's API constraints:

• Partial discovery: Typically finds 3-6 time periods (Google's web interface may show 10+ periods)
• API limitations: Google's Map Tiles API doesn't expose the complete historical timeline
• Recent bias: Finds dates from approximately 2015-present reliably; older imagery (pre-2015) is often not discoverable
• Variable results: Locations with frequent recapture (major streets) yield better results than rarely-captured areas
• No guaranteed coverage: Not all locations with "See more dates" in Google Maps will be fully discoverable

How it works: The tool searches for historical imagery by:

1. Starting at your location with multiple search radii (25m, 50m, 100m, 150m)
2. Following spatial links (forward/back/sideways connections between panoramas)
3. Traversing up to 7 levels deep by default (configurable to 10 with --historical-max-depth)
4. Prioritizing exploration of older dates when found

Performance:

• Default settings (depth=7, 200 panoramas): ~15-40 API calls, finds 3-6 dates
• Aggressive settings (depth=10, 500 panoramas): ~30-100 API calls, finds 4-8 dates

The tool uses advanced techniques to maximize discovery within API constraints, but cannot access Google's complete internal historical database. For comprehensive historical analysis, consider using the dates found here as a representative sample.

Output

Downloads create equirectangular panorama images with:

• Full resolution (typically 16384×8192 pixels with the "high" flag)
• Proper XMP metadata for 360° photo viewers
• Geographic and temporal metadata when available
• Copyright and attribution information

Files are compatible with:

• Facebook 360° photos
• VR headsets and viewers
• Google Photos spherical view
• Any software supporting equirectangular panoramas

API limits and costs

Uses Google's official Map Tiles API:

• Requires billing enabled
• No charge for less than 100k requests per month
• Quality impacts number of requests: high = 512 tiles, medium = 128 tiles, low = 32 tiles
  • Defaults to medium
• Virtually free and cheaper than commercial alternatives
• Respects Google's terms of service

Requirements

• Python 3.8+
• Google Maps API key with Map Tiles API enabled

License

MIT License

Contributing

Issues and pull requests welcome!