XYZ Map Imagery Capture API

Apify Actor/API for downloading imagery from a user-supplied, permitted XYZ tile server. It stitches the selected bounding box and stores:

• MOSAIC.png
• MOSAIC_EPSG3857.tif, written directly as a disk-backed BigTIFF with embedded GeoTIFF georeferencing
• OUTPUT JSON and one Dataset summary row

All four destinations are also declared in .actor/output_schema.json, so Apify displays the PNG, BigTIFF, summary, and Dataset as clickable Actor outputs after a run.

The input is preconfigured with a Google Satellite XYZ template. The downloader accepts standard {z}, {x}, {y} templates and also supports {s} or {snum} subdomains.

Test source

The included example is preconfigured for Google Satellite XYZ tiles:

https://mt{snum}.google.com/vt/lyrs=s&x={x}&y={y}&z={z}&hl=de

Check and follow the source's current attribution, license, acceptable-use, and rate-limit requirements before use. The API requires confirmTileServerPermission: true but cannot verify contractual permission automatically.

Local test

$env:APIFY_LOCAL_STORAGE_DIR = (Join-Path $PWD "storage")
Copy-Item .\INPUT_EXAMPLE.json .\storage\key_value_stores\default\INPUT.json -Force
python -m src.main

Install dependencies first with python -m pip install -r requirements.txt.

Apify deployment

Create a new Actor from this folder or replace the source files of a test Actor, build it, then run it with INPUT_EXAMPLE.json. External deployment and publication are intentionally left to the account owner.

Safety behavior

• Requires explicit permission confirmation.
• Accepts HTTP(S) XYZ templates only.
• Rejects missing or unknown placeholders.
• Caps zoom, parallelism, retries, timeout, decoded output size, and total tiles.
• Fails the whole run if any requested tile cannot be decoded, avoiding a silently incomplete map.
• Applies a configurable request delay and a descriptive User-Agent.

BigTIFF streaming

The GeoTIFF path preserves PyMapStitcher's direct streaming design. The Actor creates a disk-backed tifffile.memmap with bigtiff=True, writes every decoded tile directly into its final pixel window, and flushes the file after downloading. The full raster is never assembled in RAM. The completed BigTIFF is then uploaded to the run's Key-value store with a streamed HTTP request instead of read_bytes().

For local development (APIFY_IS_AT_HOME=0), no cloud token exists. The completed test files are therefore handed to the Apify SDK and written into APIFY_LOCAL_STORAGE_DIR. Cloud runs keep the streamed upload path.

PNG is an optional convenience preview. It is generated only for mosaics up to 100 million pixels; larger selections still produce the streamed BigTIFF and report png_skipped_due_to_size: true.