Home / Python SDK / Sample notebooks

Create a catalog order

Create and monitor catalog orders using the SDK.

Open notebook

Step 1. Set up the notebook

1. Install dependencies

Python
!pip install up42-py --upgrade -q


import up42, geojson, pathlib
from datetime import date, timedelta
from itertools import islice
from IPython.display import Image

2. Configure credentials

Run the cell below to create a credentials.json file in a directory named .up42 in your home folder.

Python
# Defines the credentials file path if it doesn't exist
credentials_file_path = pathlib.Path.home().joinpath(".up42/credentials.json")
credentials_file_path.parent.mkdir(parents=True, exist_ok=True)
credentials_file_path.touch(exist_ok=True)


# Prints the path to the file
print(f"Credentials file is located at: {credentials_file_path}")
  1. Click the link above to the created file and paste the following code:
    JSON
    {
        "username": "<your-email-address>",
        "password": "<your-password>"
    }
  2. Retrieve the email address and password used for logging into the console. Use them as values for username and password.
  3. Save the credentials.json file.

3. Authenticate and create a PySTAC client connection

Python
up42.authenticate(cfg_file=credentials_file_path)


# Use region if you're logging with the NSG service
# up42.authenticate(cfg_file=credentials_file_path, region="sa")


catalog = up42.catalog_client()

Step 2. Find and select data

1. Search the catalog for scenes

Search the catalog to find a full scene that fits your requirements. The search covers all catalog collections. To limit it to one or more collections, add the collections parameter with their IDs, for example collections=["phr", "spot"].

Python
# Define the time interval to search the last 3 months
end_date = date.today()
start_date = end_date - timedelta(days=90)


# Define search geometry
geometry = {
    "type": "Polygon",
    "coordinates": [
        [
            [13.369713, 52.452327],
            [13.369713, 52.470760],
            [13.339159, 52.470760],
            [13.339159, 52.452327],
            [13.369713, 52.452327],
        ]
    ],
}


# Search for scenes
items = list(
    catalog.search(
        intersects=geometry,
        datetime=f"{start_date}/{end_date}",
        filter={
            "op": "and",
            "args": [
                {"op": "<", "args": [{"property": "eo:cloud_cover"}, 20]},
                {"op": "<=", "args": [{"property": "gsd"}, 0.5]},
            ],
        },
        max_items=100,
    ).items()
)

Output the scenes that match the specified parameters.

Python
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")

2. Preview data

Some data hosts provide free, low-resolution quicklooks that you can view before creating an order:

  • Quicklooks are previews of full scenes. Some quicklooks may not fully match the scene they represent.
  • Thumbnails are small, light-weighted previews of full scenes. For some data hosts, thumbnails can be cropped and rotated compared to quicklooks.
Python
# Create an iterator to view quicklooks from search results
ql_items = (item for item in items if "quicklook" in item.assets)

Run this cell to view quicklooks from search results one by one:

Python
# Select the next scene that provides a quicklook
item = next(ql_items, None)
if item is None:
    raise RuntimeError("No scenes with a quicklook were found.")
print(f"Collection title:   {item.get_collection().title}")
print(f"Scene ID:           {item.id}")  # This is needed for ordering


# Download quicklook to quicklooks directory
quicklooks_dir = pathlib.Path("quicklooks")
quicklooks_dir.mkdir(exist_ok=True)
quicklook_path = item.assets["quicklook"].file.download(quicklooks_dir)
Image(quicklook_path)

3. Select a data product

Data products are a type of imagery with a specific geometric and radiometric processing level and file format. All collections have different data products corresponding to their technical specifications.

Python
# Provide scene ID or default to current quicklook
selected_id = input(f"Enter scene ID [{item.id}]: ").strip() or item.id
matches = [scene for scene in items if scene.id == selected_id]
if len(matches) != 1:
    raise RuntimeError(
        f"Expected one search result with scene ID {selected_id}, found {len(matches)}."
    )
item = matches[0]
collection = item.get_collection()
Python
# Find data products available for the scene previewed above
data_products = {
    name: asset.extra_fields["id"]
    for name, asset in collection.assets.items()
    if "data" in (asset.roles or [])
}


for name in data_products:
    asset = collection.assets[name]
    print(f"-  Title:             {asset.title}")
    print(f"   Data product name: {name}")
    print(f"   Data product ID:   {asset.extra_fields.get('id')}")
    print(f"   Description:       {asset.description}\n")
Python
# Select a data product for ordering from the ones printed above
available = list(data_products)
if not available:
    raise RuntimeError("No data products are available for this scene.")
default_name = available[0]
data_product_name = (
    input(f"Enter data product name [{default_name}]: ").strip() or default_name
)
if data_product_name not in data_products:
    raise RuntimeError(
        f"{data_product_name} is not a data product of this scene. "
        f"Available products: {', '.join(available)}."
    )
data_product_id = data_products[data_product_name]

Step 3. Get access

Once you’ve found a scene you want to order, check the requirements of its collection and review its EULA.

1. Request access

Some collections require an access approval before you can order them. Check if the collection of the chosen scene requires one.

Python
# Retrieve the selected collection
print(f"Collection ID: {collection.id}")
print(f"Collection title: {collection.title}")


if collection.extra_fields.get("access:approval_required"):
    print("You need to request access first")
else:
    print("No access request is required")

If needed, request access to the collection. Your request will be reviewed in up to 3 working days. You’ll get an email once a decision has been reached.

2. Accept the EULA

If you want to order the collection for the first time, review and accept its end-user license agreement (EULA). If a EULA is updated, you need to re-accept it before creating your next order.

Step 4. Create an order

1. Fill out an order form

Create an order template for the chosen scene and data product.

Python
features = geojson.FeatureCollection(features=[geojson.Feature(geometry=geometry)])
order_template = up42.BatchOrderTemplate(
    data_product_id=data_product_id,
    display_name=f"{data_product_name}-{date.today()}",
    features=features,
    params={"id": item.id},
    tags=["sdk", data_product_name],
)

2. Estimate the cost

Before creating an order, estimate the price in UP42 credits. The factors considered in the final price calculation are the size of the area of interest, the data collection, and the type of data product.

Python
order_template.estimate

The response returns the overall credit amount that will be deducted from your credit balance if you decide to proceed with the ordering.

3. Create an order

Create an order with the requested parameters.

Credits will be deducted upon successful completion of the created catalog order. The transaction can’t be reversed.

Python
order_references = order_template.place()
order_reference = order_references[0]
if not hasattr(order_reference, "order"):
    raise RuntimeError(order_reference.message)
order = order_reference.order
order

Step 5. Monitor and download

To learn about the time frames of catalog orders, see Asset delivery time.

Check the status of your order. The following order statuses mean you can download assets from storage:

  • BEING_FULFILLED Some order assets might have been delivered.
  • FULFILLED All order assets have been delivered.
Python
order.status

You can also track the order until it is fulfilled. Tracking waits until the status is FULFILLED and raises an error if the order fails or is canceled.

Python
order.track(report_time=150)