Skip to main content

End-to-End Python Workflow

Use this script as a runnable baseline for API-first integration. It demonstrates one safe path: estimate -> create -> availability check -> composite download.

Need More Runnable Scripts?

Use Clearsky-Vision/clearsky_api_tools for additional examples (status polling, availability variants, and download patterns) plus a lightweight Python client.

Before You Start​

Minimal Request Example​

import os
from pathlib import Path

import requests

API = "https://api.clearsky.vision"
HEADERS = {
    "x-api-key": os.environ["CLEARSKY_API_KEY"],
    "Content-Type": "application/json",
}

order_body = {
    "Wkt": "POLYGON((9.8778932067 56.4785666824,10.1964967224 56.4785666824,10.1964967224 56.2778208778,9.8778932067 56.2778208778,9.8778932067 56.4785666824))",
    "SatelliteConstellations": ["Sentinel1", "Sentinel2", "Landsat89"],
    "Model": "Stratus2",
    "StorageMonths": 1,
    "ApiRequests": 1,
    "ImageFrequency": 3,
    "ReferenceDate": "2025-01-01",
    "From": "2025-04-01",
    "To": None,
}

def post_json(path, body, stream=False):
    response = requests.post(f"{API}{path}", headers=HEADERS, json=body, stream=stream, timeout=120)
    response.raise_for_status()
    return response

# 1) Estimate order cost and feasibility
estimate = post_json("/api/tasking/orders/estimate", order_body)
print("estimate ok", estimate.status_code)

# 2) Create order with same validated payload
create = post_json("/api/tasking/orders", order_body)
print("create ok", create.status_code)

# 3) Validate single-date download availability
availability_body = {
    "Wkt": order_body["Wkt"],
    "Date": "2025-04-03T00:00:00Z",
    "Model": order_body["Model"],
    "SatelliteConstellations": order_body["SatelliteConstellations"],
    "EpsgProjection": 32632,
    "Bandnames": "rgb",
}

availability = post_json("/api/satelliteimages/process/composite/available", availability_body)
print("availability ok", availability.status_code)

# 4) Download image bytes
process_body = {
    "Wkt": order_body["Wkt"],
    "Date": "2025-04-03T00:00:00Z",
    "Resolution": 10,
    "EpsgProjection": 32632,
    "Model": order_body["Model"],
    "SatelliteConstellations": order_body["SatelliteConstellations"],
    "Bandnames": "rgb",
}

image = post_json("/api/satelliteimages/process/composite", process_body, stream=True)
output = Path("clearsky_rgb.tif")
with output.open("wb") as fh:
    for chunk in image.iter_content(1 << 20):
        if chunk:
            fh.write(chunk)

print("saved", output.resolve())

Common Failure and Fix​

  • Failure: script works for estimate/create but fails at download.
  • Fix:
    • run availability with the final process payload settings,
    • keep Model and SatelliteConstellations aligned between calls,
    • add retry/backoff for 429 and 5xx in your production wrapper.

For status-specific behavior, use Error codes and Request limits.

Next Step​