# 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 |