Download with the API

Use API downloads for automation and large-scale workflows.

Typical Sequence

1. Confirm availability.
2. Estimate processing-unit cost.
3. Request composite/tile/minitile output.
4. Choose a delivery mode: store response bytes, use UploadUrl, or use Business-managed S3 pushing if your account has that setup.

Delivery Modes

ClearSKY supports three distinct ways to deliver downloadable imagery. Two are available in standard API workflows. Business-managed S3 pushing is a separate plan-level delivery feature that requires ClearSKY setup with your S3-compatible storage.

Mode	Who controls the destination	How delivery works	Available to	Typical use cases
Direct byte download	Your client	ClearSKY returns the file as a binary response, and your client stores it locally or forwards it to your own storage.	All API users	Custom pipelines, scripts, and integrations where you want full control of the file handling.
UploadUrl	Your request payload	You provide a writable upload target, and ClearSKY sends the file there instead of returning bytes to the client.	All users on supported download endpoints	Server-side handoff into a signed URL, bucket, or internal object store.
Business-managed S3 pushing	ClearSKY after setup with your credentials	ClearSKY pushes imagery directly to customer-owned S3-compatible storage that was configured through Business onboarding/support.	Business customers with this feature enabled	Production workflows that need automatic delivery without client-side download handling.

Direct Byte Download

Use direct byte download when your application can receive the response body and decide where to store it.

1. Call the download endpoint.
2. Stream the response bytes to disk, object storage, or another internal destination.
3. Handle retries/backoff and attribution in your own pipeline.

UploadUrl

Use UploadUrl when you want ClearSKY to write the file to a destination you already control.

1. Create or obtain a writable upload target.
2. Pass that target as UploadUrl in the download request.
3. ClearSKY uploads the file directly to that URL.

UploadUrl still requires customer orchestration

UploadUrl changes where the file is delivered, but you still need to check availability, send the download request, and manage the workflow yourself. Business-managed S3 pushing is different: it is a setup where ClearSKY pushes imagery into your S3-compatible storage after coordination with support.

Business-Managed S3 Pushing

Use Business-managed S3 pushing when you want ClearSKY to deliver imagery automatically into your own S3-compatible storage without client-side download handling.

1. Contact ClearSKY to enable the Business delivery workflow.
2. Share the S3-compatible storage credentials and destination details your organization controls.
3. ClearSKY pushes the imagery directly to that storage after processing.
4. Your downstream systems pick up the files from your bucket without needing to poll for binary downloads.

Choosing an Endpoint Type

• POST /api/satelliteimages/process/composite is the default for most download workflows.
• You can use the composite endpoint even when the original order was tile/minitile-based.
• POST /api/satelliteimages/process/tile and POST /api/satelliteimages/process/minitile are typically used for very large, grid-based retrieval and finer control near UTM transition zones.
• Composite downloads use geometry inputs; tile/minitile requests use GUID-based inputs.

Example Flow (Composite)

1. Call POST /api/satelliteimages/process/composite/available with your AOI/date/model inputs.
2. Call POST /api/satelliteimages/process/composite/estimate using the same payload shape.
3. Validate estimate output (processing units, runtime, size) against your workflow budget.
4. Call POST /api/satelliteimages/process/composite with the approved payload.
5. Save direct response bytes, or provide UploadUrl for server-side delivery.

Minimal composite request body (Wkt mode):

{
  "Wkt": "POLYGON ((9.877893206725581 56.47856668238974, 10.196496722350581 56.47856668238974, 10.196496722350581 56.27782087776097, 9.877893206725581 56.27782087776097, 9.877893206725581 56.47856668238974))",
  "Date": "2024-05-03T00:00:00Z",
  "Resolution": 10,
  "EpsgProjection": 32632,
  "Model": "Stratus2",
  "SatelliteConstellations": ["Sentinel1", "Sentinel2", "Landsat89"],
  "Bandnames": "all"
}

Use one geometry mode per request: send Wkt or GeoJson, not both.

Main Endpoints

• POST /api/satelliteimages/process/composite/available
• POST /api/satelliteimages/process/composite/estimate
• POST /api/satelliteimages/process/composite
• POST /api/satelliteimages/process/tile
• POST /api/satelliteimages/process/minitile

Implementation Notes

• Keep estimate and download payloads aligned to avoid budget mismatches.
• Handle rate limits and transient failures with retry/backoff (429, 5xx).
• Prefer UploadUrl for async pipelines that should not hold large binary responses in memory.
• Use Business-managed S3 pushing only when your account has been set up for that plan-level delivery mode.

For full request/response definitions, see Processing / download endpoints.

For attribution implementation guidance, see Source attribution and external use.