Home / Python SDK

SDK quick start

Learn your way around the UP42 platform using our Python SDK.

Step 1. Create an account

Create an UP42 account to access the SDK.

Step 2. Install the SDK and authenticate

Install the SDK package:

Pip
pip install up42-py
Conda
conda install -c conda-forge up42-py

Authenticate your account:

Python
import up42
up42.authenticate(
  username="[email protected]",
  password="your-password",
)

Your token will be automatically refreshed in the same session.

Step 3. Explore collections

The catalog hosts archive data: data that already exists, captured by one of the providers on our platform.

Use the code snippet below to return a complete, up-to-date list of our catalog collections:

Python
catalog = up42.catalog_client()


for collection in catalog.get_collections():
  print(f"\n{collection.title}: {collection.id}")
  print(f"{collection.description}")
  print("Metadata:")
  print(f"  Product type:       {metadata.get('productType')}")
  print(f"  Resolution class:   {metadata.get('resolutionClass')}")
  print(f"  Min resolution:     {resolution.get('minimum')} m")
  if resolution.get("maximum"): print(f"  Max resolution {resolution.get('maximum')} m")

This step’s output

All catalog collections will be returned with their metadata information, such as product type and resolution:

A screenshot of a Jupyter Notebook response listing the collections

Step 4. Search for Sentinel-2 scenes

Scenes are captures of a particular area within a specific collection. We’ll use Sentinel-2: as an open data source from the European Space Agency, it’s free.

When searching for scenes, you can select the following parameters:

  • Area of interest
  • Acquisition date
  • Maximum acceptable cloud coverage

Here’s the code you need to search for Sentinel-2 scenes:

Python
from itertools import islice


# 1. Define the area of interest (AOI)
geometry = {
    "type": "Polygon",
    "coordinates": [[
        [13.369713, 52.452327],
        [13.369713, 52.470760],
        [13.339159, 52.470760],
        [13.339159, 52.452327],
        [13.369713, 52.452327],
    ]],
}


# 2. Search for scenes from the "sentinel-2" collection
items = list(catalog.search(
    collections=["sentinel-2"],
    intersects=geometry,
    datetime="2026-06-01/2026-12-31", # From 01.06.2026 to 31.12.2026
    filter={"op": "<", "args": [{"property": "eo:cloud_cover"}, 20]}, # Cloud coverage of less than 20%
).items())


# 3. Print key information for each scene
print(f"\nFound {len(items)} scenes matching the criteria:\n")
for item in islice(items, 3): # Print first 3
    print(f"- Scene ID: {item.id}")
    print(f"  Acquisition date: {item.datetime}")
    print(f"  Cloud coverage: {item.properties.get('eo:cloud_cover')}%")
    print(f"  Resolution: {item.properties.get('gsd')} m\n")

This step’s output

Scenes matching the search criteria will be returned:

A screenshot of a Jupyter Notebook response listing the scenes

Step 5. Preview data

Before creating an order, check how your scene looks. With quicklooks, you can see a preview of your scene. Note that not all data providers provide quicklooks.

The code below will request a quicklook of the first scene:

Python
import pathlib
from IPython.display import Image, display


# 1. Select a scene
first_item = next(item for item in items if "quicklook" in item.assets)


# 2. Create a directory to save the image
output_directory = pathlib.Path("downloaded_images")
output_directory.mkdir(exist_ok=True)


# 3. Get a signed URL for the quicklook
print(f"Quicklook URL: {first_item.assets['quicklook'].file.url}")


# 4. Download the quicklook
downloaded_file_path = first_item.assets["quicklook"].file.download(output_directory)
print(f"Quicklook downloaded to: {downloaded_file_path}")


# 5. Display the downloaded image
print("\nQuicklook:")
display(Image(filename=downloaded_file_path, width=600))

This step’s output

You will get a preview of the scene: in this case, a capture of Berlin, Germany, and the surrounding state of Brandenburg. Remember that this is just a low-quality preview image, not what the final scene will look like.

A quicklook preview image of a Sentinel-2 scene

Step 6. Create an order

Create an order to get the selected Sentinel-2 scene for free with this code snippet:

Python
import geojson


# 1. Place the order and get an OrderReference
order_ref = up42.BatchOrderTemplate(
    data_product_id=data_product.id,
    display_name="Sentinel-2 demo order",
    features=geojson.FeatureCollection(features=[geojson.Feature(geometry=geometry)]),
    params={"id": scene.id},
    tags=["sdk", data_product.name]
).place()[0]


# 2. Track the order
order_id = order_ref.id
order = up42.Order.get(order_id)
order.track()

This step’s output

You will create an order and track its status:

A screenshot of a Jupyter Notebook response tracking the order status

By default, the order status will be checked every 2 minutes. It will take up to 10 minutes for the system to complete the order.

Step 7. Download the data

Once the order is complete, you can download your data. Here’s the code needed to download it:

Python
# 1. Create a PySTAC client connection
UP42_client = up42.stac_client()


# 2. Define the search filter
filter = {"op": "=", "args": [{"property": "order_id"}, order_id]}
items = UP42_client.search(filter=filter)


# 3. Create an output directory
output_dir = pathlib.Path.home() / "Desktop" / "original_zipped_deliveries"
output_dir.mkdir(parents=True, exist_ok=True)


# 4. Download the asset
for item in items.items():
  collection = item.get_collection()
  if not collection:
      continue
  original_delivery = next(
      (asset for asset in collection.assets.values() if asset.roles and "original" in asset.roles),
      None,
  )
  if original_delivery:
      downloaded_file_path = original_delivery.file.download(output_directory=output_dir)
      print(f"\nThe original delivery was downloaded to '{downloaded_file_path}'.")
      break
else:
  print(f"The original delivery wasn't found.")

This step’s output

The data will be downloaded to your device.