Orders in SDK

Overview

Create tasking and catalog orders.

View repository

Constants

Constant Description Value

Constant	Description	Value
`OrderType`	Order types: `TASKING`: Tasking orders. `ARCHIVE`: Catalog orders.	`Literal["TASKING", "ARCHIVE"]`
`OrderDetails`	Order details of both order types.	`Union[ArchiveOrderDetails, TaskingOrderDetails]`

OrderType

Order types:

TASKING: Tasking orders.
ARCHIVE: Catalog orders.

Literal["TASKING", "ARCHIVE"]

OrderDetails Order details of both order types. Union[ArchiveOrderDetails, TaskingOrderDetails]

Class: OrderParamsV2

A class that represents the schema for the order parameters.

Attributes

Attribute	Description
`dataProduct`	str The data product ID.
`displayName`	str A human-readable name that describes the order.
`params`	Dict[str, Any] Order parameters.
`featureCollection`	Dict[str, Any] A GeoJSON FeatureCollection representing the order’s geometry.
`tags`	List[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 provides sorting options for orders.

Attributes

Attribute	Description
`created_at`	utils.SortingField Sorts by creation date. The default order is ascending.
`updated_at`	utils.SortingField Sorts by update date. The default order is ascending.
`type`	utils.SortingField Sorts by order type. The default order is catalog orders first, tasking second.
`status`	utils.SortingField Sorts by order status. The default order is ascending.

1
from itertools import islice
2

3
# Sort by creation date, from the most recent to the earliest
4
orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.created_at.desc)
5

6
# Sort by the last update date, from the most recent to the earliest
7
# orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.updated_at.desc)
8

9
# Sort by order type, tasking first, catalog second
10
# orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.type.desc)
11

12
# Sort by order status, in the order of progression
13
# orders_sorted = up42.Order.all(sort_by=up42.OrderSorting.status.asc)
14

15
# Define output for one of the sorting examples
16
for order in islice(orders_sorted, 0, 5): # Print first 5 results
17
    print(f"- Order ID:     {order.id}")
18
    print(f"  Display name: {order.display_name}")
19
    print(f"  Status:       {order.status}")
20
    print(f"  Type:         {order.type}\n")

Class: ArchiveOrderDetails

A data class that represents catalog order details.

Attributes

Attribute Description

Attribute	Description
`aoi`	dict Geometry in the GeoJSON format.
`image_id`	Optional[str] The ID of the image scene.

aoi

dict

Geometry in the GeoJSON format.

image_id

Optional[str]

The ID of the image scene.

1
# Select a catalog order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
6

7
# Define output from the Order class
8
print(f"Order details for ID: {order.id}")
9
print(f"Display name:         {order.display_name}")
10
print(f"Status:               {order.status}")
11
print(f"Type:                 {order.type}")
12
print(f"Data product ID:      {order.data_product_id}")
13
print(f"Tags:                 {', '.join(order.tags) if order.tags else 'No tags'}")
14

15
# Define output from the ArchiveOrderDetails class
16
print("\nCatalog-specific details:")
17
print(f"Image ID:           {order.details.image_id}")
18
print(f"Geometry:           {order.details.aoi}")

Class: TaskingOrderDetails

A data class that represents tasking order details.

Attributes

Attribute	Description
`acquisition_start`	str The date and time when the sensor started the acquisition process.
`acquisition_end`	str The date and time when the sensor finished the acquisition process.
`geometry`	dict Geometry in the GeoJSON format.
`extra_description`	Optional[str] An additional order description.
`sub_status`	Optional[OrderSubStatus] An additional status for the tasking order.
`acquisition_mode`	Optional[str] A tasking order parameter that represents the operation mode specifying the way the images will be taken.
`max_cloud_cover`	Optional[int] A tasking order parameter that represents the maximum percentage of a delivered asset that can be covered by clouds.
`max_incidence_angle`	Optional[int] A tasking order parameter that represents the maximum allowed angle between the ground normal and look direction from the satellite.
`geometric_processing`	Optional[str] A tasking order parameter that represents the level of geometric transformation and manipulation applied to data.
`projection`	Optional[str] A tasking order parameter that represents the projection reference system that will be used for the processing and georeferencing.
`pixel_coding`	Optional[str] A tasking order parameter that represents the number of bits used to represent the color or intensity of a single pixel in a digital image.
`radiometric_processing`	Optional[str] A tasking order parameter that represents the level of radiometric transformation and manipulation applied to data.
`spectral_bands`	Optional[str] A tasking order parameter that represents spectral bands, that is, specific ranges of wavelengths on the spectrum. They can be delivered separately or as combinations or bundles.
`priority`	Optional[str] A tasking order parameter that represents the priority of the order.
`min_bh`	Optional[int] A tasking order parameter that represents the lower limit on the baseline-to-height ratio that determines how close apart stereo or tri-stereo images will be taken relative to the height of the passing imaging system.
`max_bh`	Optional[int] A tasking order parameter that represents the upper limit on the baseline-to-height ratio that determines how close apart stereo or tri-stereo images will be taken relative to the height of the passing imaging system.
`resolution`	Optional[str] A tasking order parameter that represents the ability to distinguish objects in an image. The higher the resolution of a given collection, the more pixels there are per unit area, and the more detailed ground objects are.
`polarization`	Optional[str] A tasking order parameter that represents the direction of travel of an electromagnetic wave: vertical (V) or horizontal (H). The first letter corresponds to how signals are emitted, and the second letter corresponds to how they are received.
`scene_size`	Optional[str] A tasking order parameter that represents the sizes of delivered scenes intersecting the defined AOI or POI.
`looks`	Optional[str] A tasking order parameter that represents the number of times a sensor captures the target.

1
# Select a tasking order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
9 collapsed lines
6

7
# Define output from the Order class
8
print(f"Order details for ID:         {order.id}")
9
print(f"Display name:                 {order.display_name}")
10
print(f"Status:                       {order.status}")
11
print(f"Type:                         {order.type}")
12
print(f"Data product ID:              {order.data_product_id}")
13
print(f"Tags:                         {', '.join(order.tags) if order.tags else 'No tags'}")
14

15
# Define output from the TaskingOrderDetails class
16
# Parameters fo optical and SAR collections
17
print("\nTasking-specific details:")
18
print(f"Substatus:                    {order.details.sub_status}")
19
print(f"Acquisition start:            {order.details.acquisition_start}")
20
print(f"Acquisition end:              {order.details.acquisition_end}")
21
print(f"Extra description:            {order.details.extra_description}")
22
print(f"Geometry:                     {order.details.geometry}")
23
print(f"Acquisition mode:             {order.details.acquisition_mode}")
24
print(f"Maximum incidence angle:      {order.details.max_incidence_angle}")
25
print(f"Priority:                     {order.details.priority}")
26
# Parameters only for optical collections
10 collapsed lines
27
print(f"Maximum cloud coverage:       {order.details.max_cloud_cover}")
28
print(f"Geometric processing level:   {order.details.geometric_processing}")
29
print(f"Coordinate reference system:  {order.details.projection}")
30
print(f"Bit depth per pixel:          {order.details.pixel_coding}")
31
print(f"Radiometric processing level: {order.details.radiometric_processing}")
32
print(f"Spectral bands combination:   {order.details.spectral_bands}")
33
print(f"Minimum B/H ratio:            {order.details.min_bh}")
34
print(f"Maximum B/H ratio:            {order.details.max_bh}")
35
print(f"Resolution:                   {order.details.resolution}")
36
print(f"Scene size:                   {order.details.scene_size}")
37
# Parameters only for SAR collections
2 collapsed lines
38
print(f"Polarization:                 {order.details.polarization}")
39
print(f"Number of looks:              {order.details.looks}")

Class: Order

A data class that represents an order in the system.

Attributes

Attribute	Description
`id`	str The order ID.
`display_name`	str A human-readable name that describes the order.
`status`	OrderStatus The order status.
`workspace_id`	str The workspace ID.
`account_id`	str The account ID.
`type`	OrderType The order type.
`details`	Optional[OrderDetails] Order details.
`data_product_id`	Optional[str] The data product ID.
`tags`	Optional[list[str]] A list of tags that categorize the order. A tag can consist of letters, numbers, spaces, and special characters (`.`, `-`, `_`, `/`, `:`).

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
6

7
# Define output
8
print(f"Order details for ID: {order.id}")
9
print(f"Display name:         {order.display_name}")
10
print(f"Status:               {order.status}")
11
print(f"Type:                 {order.type}")
12
print(f"Data product ID:      {order.data_product_id}")
13
print(f"Order tags:           {', '.join(order.tags) if order.tags else 'No tags'}")

Properties

order_details

This property is deprecated and will be removed in 3.0.0. Use the Order class’s details attribute.

Retrieves the details of a specific order. Returns dict.

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
6
order.order_details

order_id

This property is deprecated and will be removed in 3.0.0. Use the Order class’s id attribute.

Retrieves the order ID. Returns str.

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
6
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.

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
6
order.is_fulfilled

Methods

get

Retrieves a specific order by its ID. Returns Order.

Parameter Description

Parameter	Description
`order_id`	str The order ID.

order_id

str

The order ID.

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order info
5
order = up42.Order.get(order_id=order_id)
6

7
# Define output
8
print(f"Order details for ID: {order.id}")
9
print(f"Display name:         {order.display_name}")
10
print(f"Status:               {order.status}")
11
print(f"Type:                 {order.type}")
12
print(f"Data product ID:      {order.data_product_id}")
13
print(f"Order tags:           {', '.join(order.tags) if order.tags else 'No tags'}")

all

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

Parameter	Description
`workspace_id`	Optional[str] The workspace ID. Use to get jobs from a specific workspace. Otherwise, jobs from the entire account will be returned.
`order_type`	Optional[OrderType] The type of orders to return. To get orders of all types, omit the parameter.
`status`	Optional[List[OrderStatus]] Order statuses. Use to search for orders with any of the provided statuses.
`sub_status`	Optional[List[OrderSubStatus]] Order sub-statuses. Use to search for orders with any of the provided sub-statuses.
`display_name`	Optional[str] Additional search terms. Use to search for orders that contain the provided search query in their name.
`tags`	Optional[List[str]] A list of tags that categorize the order.
`sort_by`	Optional[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`.

1
from itertools import islice
2

3
# Search for orders
4
orders = up42.Order.all(
5
    order_type="TASKING",
6
    status=["FULFILLED", "PLACED"],
7
    sort_by=up42.OrderSorting.status.asc,
8
)
9

10
# Define output
11
for order in islice(orders, 0, 5): # Print first 5 results
12
    print(f"- Order ID:         {order.id}")
13
    print(f"  Display name:     {order.display_name}")
14
    print(f"  Status:           {order.status}")
15
    print(f"  Type:             {order.type}")
16
    print(f"  Data product ID:  {order.data_product_id}")
17
    print(f"  Order tags:       {', '.join(order.tags) if order.tags else 'No tags'}\n")

get_assets

This method is deprecated and will be removed in 3.0.0. Use the search method.

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

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Fetch order assets
5
order = up42.Order.get(order_id=order_id)
6
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.

Parameter Description

Parameter	Description
`report_time`	float An interval between queries, in seconds. The default value is `120`.

report_time

float

An interval between queries, in seconds. The default value is 120.

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Track status
5
order = up42.Order.get(order_id=order_id)
6
order.track(report_time=150)

track_status

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

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.

Parameter Description

Parameter	Description
`report_time`	float An interval between queries, in seconds. The default value is `120`.

report_time

float

An interval between queries, in seconds. The default value is 120.

1
# Select an order
2
order_id = "3bf00b63-7188-4b04-aa27-d78e4cd32c01"
3

4
# Track status
5
order = up42.initialize_order(order_id=order_id)
6
order.track_status(report_time=150)

Learn more

API docs | Tasking Console docs | Tasking

API docs | Catalog Console docs | Catalog