Orders in SDK

Order tasking and catalog imagery using the SDK.


Overview

Create tasking and catalog orders.

View repository

Constants

ConstantDescriptionValue
OrderTypeOrder types:
  • TASKING: Tasking orders.
  • ARCHIVE: Catalog orders.
Literal["TASKING", "ARCHIVE"]
OrderDetailsOrder details of both order types.Union[ArchiveOrderDetails, TaskingOrderDetails]

Class: OrderParamsV2

A class that represents the schema for the order parameters.

Attributes

AttributeDescription
dataProductstr
The data product ID.
displayNamestr
A human-readable name that describes the order.
paramsDict[str, Any]
Order parameters.
featureCollectionDict[str, Any]
A GeoJSON FeatureCollection representing the order’s geometry.
tagsList[str]
A list of tags that categorize the order. A tag can consist of letters, numbers, spaces, and special characters (., -, _, /, :).

Class: OrderSorting

A class that contains predefined sorting fields.

Attributes

AttributeDescription
created_atutils.SortingField
Sorts by creation date. The default order is ascending.
updated_atutils.SortingField
Sorts by update date. The default order is ascending.
typeutils.SortingField
Sorts by order type. The default order is catalog orders first, tasking second.
statusutils.SortingField
Sorts by order status. The default order is ascending.
Python
# Sort by creation date, from the most recent to the earliest
orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.created_at.desc)
# Sort by the last update date, from the most recent to the earliest
# orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.updated_at.desc)
# Sort by order type, tasking first, catalog second
# orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.type.desc)
# Sort by order status, in the order of progression
# orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.status.asc)
# Define output for one of the sorting examples
for order in list(orders_sorted)[:5]: # Print first 5 results
print(f"- Order ID: {order.id}")
print(f" Status: {order.status}")
print(f" Type: {order.type}")
print(f" Created at: {order.info['createdAt']}\n")

Class: ArchiveOrderDetails

A data class that represents catalog order details.

Attributes

AttributeDescription
aoidict
Geometry in the GeoJSON format.
image_idOptional[str]
The ID of the image scene.
Python
# Select a catalog order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)
details = order.details
tags = order.tags
# Define output from the Order class
print(f"Order details for ID: {order.id}")
print(f"Display name: {order.display_name}")
print(f"Status: {order.status}")
print(f"Type: {order.type}")
print(f"Data product ID: {order.data_product_id}")
print(f"Tags: {', '.join(tags) if tags else 'No tags'}")
# Define output from the ArchiveOrderDetails class
print("\nCatalog-specific details:")
print(f" Image ID: {details.image_id}")
print(f" Geometry: {details.aoi}")

Class: TaskingOrderDetails

A data class that represents tasking order details.

Attributes

AttributeDescription
acquisition_startstr
The date and time when the sensor started the acquisition process.
acquisition_endstr
The date and time when the sensor finished the acquisition process.
geometrydict
Geometry in the GeoJSON format.
extra_descriptionOptional[str]
An additional order description.
sub_statusOptional[OrderSubStatus]
An additional status for the tasking order.
Python
# Select a tasking order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)
details = order.details
tags = order.tags
# Define output from the Order class
6 collapsed lines
print(f"Order details for ID: {order.id}")
print(f"Display name: {order.display_name}")
print(f"Status: {order.status}")
print(f"Type: {order.type}")
print(f"Data product ID: {order.data_product_id}")
print(f"Tags: {', '.join(tags) if tags else 'No tags'}")
# Define output from the TaskingOrderDetails class
print("\nTasking-specific details:")
print(f" Substatus: {details.sub_status}")
print(f" Acquisition start: {details.acquisition_start}")
print(f" Acquisition end: {details.acquisition_end}")
print(f" Extra description: {details.extra_description}")
print(f" Geometry: {details.geometry}")

Class: Order

A data class that represents an order in the system.

Attributes

AttributeDescription
idstr
The order ID.
display_namestr
A human-readable name that describes the order.
statusOrderStatus
The order status.
workspace_idstr
The workspace ID.
account_idstr
The account ID.
typeOrderType
The order type.
detailsOptional[OrderDetails]
Order details.
data_product_idOptional[str]
The data product ID.
tagsOptional[list[str]]
A list of tags that categorize the order. A tag can consist of letters, numbers, spaces, and special characters (., -, _, /, :).
Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)
tags = order.tags
# Define output
print(f"Order details for ID: {order.id}")
print(f"Display name: {order.display_name}")
print(f"Status: {order.status}")
print(f"Type: {order.type}")
print(f"Data product ID: {order.data_product_id}")
print(f"Tags: {', '.join(tags) if tags else 'No tags'}")

Properties

order_details

This property is deprecated and will be removed in 3.0.0. Use Order.details.

Retrieves the details of a specific order. Returns dict.

Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)
order.order_details

order_id

This property is deprecated and will be removed in 3.0.0. Use Order.id.

Retrieves the order ID. Returns str.

Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)
order.order_id

is_fulfilled

Checks if the order is fulfilled. Returns bool:

  • True: The order has the FULFILLED status.
  • False: The order has any other status.
Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)
order.is_fulfilled

Methods

get

Retrieves a specific order by its ID. Returns Order.

ParameterDescription
order_idstr
The order ID.
Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order info
order = up42.Order.get(order_id=order_id)

all

Retrieves all orders, with optional filtering. Returns Iterator["Order"]. Use itertools.islice to offset and limit the results.

ParameterDescription
workspace_idOptional[str]
The workspace ID. Use to get jobs from a specific workspace. Otherwise, jobs from the entire account will be returned.
order_typeOptional[OrderType]
The type of orders to return. To get orders of all types, omit the parameter.
statusOptional[List[OrderStatus]]
Order statuses. Use to search for orders with any of the provided statuses.
sub_statusOptional[List[OrderSubStatus]]
Order sub-statuses. Use to search for orders with any of the provided sub-statuses.
display_nameOptional[str]
Additional search terms. Use to search for orders that contain the provided search query in their name.
tagsOptional[List[str]]
A list of tags that categorize the order.
sort_byOptional[utils.SortingField]
The results sorting method that arranges elements in ascending or descending order based on a chosen field. To view the list of possible values, see OrderSorting.
Python
# Search for orders
orders = up42.Order.all(
order_type="TASKING",
status=["FULFILLED", "PLACED"],
sort_by=up42.OrderSorting.status.asc,
)
# Define output
for order in orders:
print(f"- Order ID: {order.id}")
print(f" Display name: {order.display_name}")
print(f" Status: {order.status}")
print(f" Type: {order.type}")
tag_string = ", ".join(order.tags) if order.tags else "No tags"
print(f" Tags: {tag_string}\n")

get_assets

This method is deprecated and will be removed in 3.0.0.

Retrieves assets from orders that have FULFILLED or BEING_FULFILLED statuses. Returns List[asset.Asset].

Use this function to retrieve multiple assets from the same order. To search across all assets in your storage, use the get_assets function from the Storage class.

Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Fetch order assets
order = up42.Order.get(order_id=order_id)
order.get_assets()

track

Tracks the order status by retrying until the status changes to FULFILLED or FAILED_PERMANENTLY. It will query the order every 120 seconds.

ParameterDescription
report_timefloat
An interval between queries, in seconds. The default value is 120.
Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Track status
order = up42.Order.get(order_id=order_id)
order.track(report_time=150)

track_status

This method is deprecated and will be removed in 3.0.0. Use Order.track.

Tracks the order status by retrying until the status changes to FULFILLED or FAILED_PERMANENTLY. It will query the order every 120 seconds. Returns str.

ParameterDescription
report_timefloat
An interval between queries, in seconds. The default value is 120.
Python
# Select an order
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
# Track status
order = up42.initialize_order(order_id=order_id)
order.track_status(report_time=150)

Learn more


Last updated: