satellite-provider/_docs/00_problem/data_parameters.md

Data Parameters

Input Data

API Request: Single Tile Download

Parameter	Type	Required	Constraints	Description
latitude	double	yes	-90 to 90	Center latitude
longitude	double	yes	-180 to 180	Center longitude
zoomLevel	int	yes	1–20	Google Maps zoom level

API Request: Tile Inventory — POST /api/satellite/tiles/inventory (AZ-505; renamed AZ-794, strict-validated AZ-796 — cycle 7)

Exactly one of tiles OR locationHashes must be populated and non-empty. Strict input validation enforced by InventoryRequestValidator + System.Text.Json (UnmappedMemberHandling.Disallow); failures return HTTP 400 + ValidationProblemDetails per _docs/02_document/contracts/api/error-shape.md v1.0.0.

Parameter	Type	Required	Constraints	Description
tiles	array	XOR (vs locationHashes)	1 ≤ count ≤ 5000	Form A: coords-by-value batch
tiles[].z	int	yes ([JsonRequired])	0–22 (slippy zoom range)	Slippy zoom level (renamed from tileZoom by AZ-794)
tiles[].x	int	yes ([JsonRequired])	0 ≤ x < 2^z	Slippy x at that zoom (renamed from tileX by AZ-794)
tiles[].y	int	yes ([JsonRequired])	0 ≤ y < 2^z	Slippy y at that zoom (renamed from tileY by AZ-794)
locationHashes	array	XOR (vs tiles)	1 ≤ count ≤ 5000	Form B: hashes-by-reference batch (UUIDv5 of "{z}/{x}/{y}")

API Request: Region

Parameter	Type	Required	Constraints	Description
latitude	double	yes	-90 to 90	Region center latitude
longitude	double	yes	-180 to 180	Region center longitude
sizeMeters	double	yes	> 0	Square region side length in meters
zoomLevel	int	yes	1–20	Tile zoom level
stitchTiles	bool	no	default: false	Whether to produce composite image

API Request: Route Creation

Parameter	Type	Required	Constraints	Description
id	UUID	yes	—	Client-generated route ID
name	string	yes	max 200 chars	Human-readable route name
description	string	no	—	Optional description
regionSizeMeters	double	yes	> 0	Size of region per route point
zoomLevel	int	yes	1–20	Tile zoom level
points	array	yes	≥ 2 waypoints	Ordered route waypoints
points[].lat	double	yes	-90 to 90	Waypoint latitude
points[].lon	double	yes	-180 to 180	Waypoint longitude
geofences	object	no	—	Optional geofence definitions
geofences.polygons[]	array	no	—	Rectangle boundaries
geofences.polygons[].northWest	GeoPoint	yes (if polygon)	valid lat/lon, non-zero	NW corner
geofences.polygons[].southEast	GeoPoint	yes (if polygon)	valid lat/lon, non-zero	SE corner
requestMaps	bool	no	default: false	Whether to download map tiles for route
createTilesZip	bool	no	default: false	Whether to produce ZIP archive

Output Data

Tile File

• Format: JPEG
• Path: ./tiles/{zoom}/{x}/{y}.jpg
• Size: ~50–100 KB per tile (typical at zoom 18)

Region Outputs

File	Format	Path Pattern	Content
CSV manifest	CSV	./ready/region_{id}_ready.csv	Tile coordinates and file paths
Summary	TXT	./ready/region_{id}_summary.txt	Processing statistics
Stitched image	JPEG	./ready/region_{id}_stitched.jpg	Composite tile image

Route Outputs

File	Format	Path Pattern	Content
Stitched map	JPEG	./ready/route_{id}_stitched.jpg	Full route composite with markers
Tiles ZIP	ZIP	./ready/route_{id}_tiles.zip	All tiles (max 50 MB)
CSV	CSV	./ready/route_{id}_ready.csv	Tile manifest
Summary	TXT	./ready/route_{id}_summary.txt	Route processing statistics

Configuration Parameters

MapConfig (provider-specific; e.g., Google Maps — each provider has its own config section)

Parameter	Type	Default	Description
ApiKey	string	—	Provider authentication token
TileSizePixels	int	256	Tile image dimension
MaxZoomLevel	int	20	Maximum allowed zoom
DefaultZoomLevel	int	18	Default when not specified

StorageConfig

Parameter	Type	Default	Description
TilesDirectory	string	"./tiles"	Root tile storage path
ReadyDirectory	string	"./ready"	Output artifacts path

ProcessingConfig

Parameter	Type	Default	Description
MaxConcurrentDownloads	int	4	Parallel Google Maps requests
MaxConcurrentRegions	int	20	Parallel region processing
QueueCapacity	int	1000	Max pending region requests