How to order archive data with UP42's Python SDK

There are a few different options for getting data from the UP42 platform. Developer-focused, and not so developer-focused.

The not-so-developer-focused way is our console, which you can access through the browser. It’s a good starting point for new users, since it gives you a map overview, the list of data providers, and lots of reminders about order options. Our smaller customers use it all the time. And our big customers often use it to check on new collections or to get map overviews of their orders.

But for placing higher volumes of orders, the Python SDK is the way. In this post, we’ll explain how to use our freely available sample data to order archive data from our catalog.

The UP42 catalog & getting started with the Python SDK

The catalog hosts archive data: data that already exists, captured by one of the many providers on our platform. Because we have some free archive data, following the instructions in this article won't cost you a single cent (or the smallest unit of currency wherever you're located).

Before accessing the catalog via the Python SDK, you'll need to create your account, if you don't have one already. Sign up here and verify your email in the console.

Next, you'll need to install the Python SDK. Installation instructions can be found here. Or, you can use the code snippets below.

If using Pip (Python package manager):

pip install up42-py

If using Conda (system package manager):

conda install -c conda-forge up42-py

Then, follow the steps in our documentation to authenticate your account. Your token will be automatically refreshed in the same session.

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

Now, it's time to start exploring.

How to explore the catalog with the Python SDK

Our glossary provides information about all our data offerings, which are referred to as collections. Currently, we have 80 different archive collections, from optical and radar satellites to elevation data.

Because the catalog only contains existing data, using the SDK to explore its offerings is free: you'll be running code that will present you with all the various options.

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

archive_collections = up42.ProductGlossary.get_collections(
   collection_type = up42.CollectionType.ARCHIVE,
   sort_by = up42.CollectionSorting.name.asc,
)

for collection in archive_collections:
   print(f"\n{collection.title}: {collection.name}")
   print(f"{collection.description}")
   print("Metadata:")
   print(f"  Product type:       {collection.metadata.product_type}")
   print(f"  Resolution class:   {collection.metadata.resolution_class}")
   print(f"  Min resolution:     {collection.metadata.resolution_value.minimum} m")
   if collection.metadata.resolution_value.maximum: print(f"  Max resolution {collection.metadata.resolution_value.maximum} m")

You’ll receive all catalog collections and their metadata information, such as product type and resolution:

Now that you have the list of collections, let's get more specific and find you a scene. Scenes are captures of a particular area by a particular collection.

In this article, we'll use Sentinel-2: as an open data source from the European Space Agency (ESA), it's free.

When searching for scenes, there are lots of parameters you can choose from, including:

• Area of interest: your desired area of interest (AOI for short). If you have a specific location in mind, you can input the coordinates and view all the collections that have archive data of your AOI. The input method for an AOI is as a geometry.

• Acquisition time: If you have a desired date range, you can input it here as a start date and end date.

• Cloud coverage: you can specify the maximum acceptable cloud coverage for your search. Often, small amounts of cloud cover can still result in acceptable data, but this varies on an order-by-order basis.

Here's the code you need to search for a Sentinel-2 scene:

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. Get the collection, host, and data product
archive_collections = up42.ProductGlossary.get_collections(
   collection_type = up42.CollectionType.ARCHIVE,
   sort_by = up42.CollectionSorting.name.asc,
)
collection = next(c for c in archive_collections if c.name == "sentinel-2")
host = next(p for p in collection.providers if p.is_host)
data_product = next(p for p in collection.data_products if "sentinel-2-level-2a" in p.name)

#3. Search for scenes from the "sentinel-2" collection
scenes = list(host.search(
   collections=["sentinel-2"],
   intersects=geometry,
   start_date="2023-06-01", # Start date is 01.06.2024
   end_date="2024-12-31", # End date is 31.12.2024
   query={"cloudCoverage": {"LT": 20}} # Cloud coverage of 20% or less
))

#4. Print key information for each scene
print(f"Found {len(scenes)} scenes matching the criteria:\n")
for scene in islice(scenes, 3): # Print first 3
   print(f"- Scene ID: {scene.id}")
   print(f"  Acquisition date: {scene.datetime}")
   print(f"  Cloud coverage: {scene.cloud_coverage}%")
   print(f"  Resolution: {scene.resolution} m\n")

And here’s the output. In our case, we found 68 scenes matching the criteria and displayed the first three:

Before placing a full order, you may want to see how your scene looks. With quicklooks, you can see a preview of your scene. Note that not all data providers provide quicklooks. Luckily for us, ESA does.

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

import pathlib
from IPython.display import Image, display

# 1. Select a scene
first_scene = scenes[0]  # Get the first scene from your results

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

# 3. Download the quicklook
downloaded_file_path = first_scene.quicklook.download(output_directory)
print(f"Quicklook downloaded to: {downloaded_file_path}")

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

And here’s what we get:

Nice. There’s a preview of your scene: in this case, a capture of Berlin, Germany, and the surrounding state of Brandenburg. Remember: this is just a preview image, not what the final scene will look like.

Time to place a full order.

How to place an order with the UP42 Python SDK

To create a full order with Sentinel-2 (and once again: it’s free), use the code below.

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()

While your order is in progress, you can check on your order status:

As we can see, the order status was updated every 120 seconds (this is the default order time). After about 6 minutes, the order was completed.

Lastly, once the order is complete, you can download your data. Here's the code needed to download:

# 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.")

Easy, right? You now know how to search for collections, preview scenes, place orders, track your progress, and download your final data with the UP42 Python SDK.

Got questions? We’re here to help. Reach out to us and we’ll get back to you ASAP. Or, check out UP42's Python SDK documentation.