Home /Python SDK/Python SDK reference

Catalog

Create and manage catalog orders using the SDK.

Overview

Get archive geospatial data from a particular date range in the past.

View repository

Class: CatalogBase

A shared class for tasking and catalog functionalities.

Examples

Python 

    tasking = up42.initialize_tasking()
catalog = up42.initialize_catalog()

tasking.get_data_product_schema(data_product_id="123eabab-0511-4f36-883a-80928716c3db")
catalog.get_data_product_schema(data_product_id="647780db-5a06-4b61-b525-577a8b68bb54")

# Order geometry
geometry = {
    "type": "Polygon",
    "coordinates": (
        (
            (13.375966, 52.515068),
            (13.375966, 52.516639),
            (13.378314, 52.516639),
            (13.378314, 52.515068),
            (13.375966, 52.515068),
        ),
    ),
}

# Estimation
catalog.estimate_order(
    order_parameters=catalog.construct_order_parameters(
        data_product_id="4f1b2f62-98df-4c74-81f4-5dce45deee99",
        image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd",
        aoi=geometry,
    ),
)

# Tasking order creation
tasking_order_parameters = tasking.construct_order_parameters(
    data_product_id="123eabab-0511-4f36-883a-80928716c3db",
    name="PNeo tasking order",
    acquisition_start="2023-11-01",
    acquisition_end="2023-12-20",
    aoi=geometry,
    tags=["project-7", "optical"],
)

tasking.place_order(
    order_parameters=tasking_order_parameters,
    track_status=True,
    report_time=150,
)

# Catalog order creation
catalog_order_parameters = catalog.construct_order_parameters(
    data_product_id="4f1b2f62-98df-4c74-81f4-5dce45deee99",
    image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd",
    aoi=geometry,
)

catalog.place_order(
    order_parameters=catalog_order_parameters,
    track_status=True,
    report_time=150,
)

Functions

get_data_product_schema

Retrieves the parameters needed to create an order for a specific data product. Returns dict.

ParameterDescription
data_product_idstr
The data product ID.

estimate_order

Estimates the cost of an order, in UP42 credits. Returns int.

ParameterDescription
order_parametersorder.OrderParams
Order parameters.

place_order

Creates a catalog or tasking order. Returns order.Order.

ParameterDescription
order_parametersorder.OrderParams
Order parameters.
track_statusbool
Determines when to return order data:
  • True: Returns order data only when the order status changes to FULFILLED or FAILED.
  • False: Returns order data immediately.
The default value is False.
report_timefloat
Use if track_status=True.

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

Class: Catalog

A class that enables access ot the catalog functionality. This class also inherits functions from the CatalogBase class.

Examples

Python 

    catalog = up42.initialize_catalog()

catalog.search(
    search_parameters=catalog.construct_search_parameters(
        geometry=up42.get_example_aoi(),
        collections=["phr"],
        start_date="2022-06-01",
        end_date="2022-12-31",
        limit=20,
        max_cloudcover=25,
    ),
    as_dataframe=False,
)

catalog.construct_order_parameters(
    data_product_id="647780db-5a06-4b61-b525-577a8b68bb54",
    image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd",
    aoi="/Users/max.mustermann/Desktop/aoi.geojson",
    tags=["project-7", "optical"],
)

catalog.download_quicklooks(
    image_ids=["a4c9e729-1b62-43be-82e4-4e02c31963dd"],
    collection="phr",
    output_directory="/Users/max.mustermann/Desktop/",
)

Functions

construct_search_parameters

Constructs search parameters. Returns dict.

ParameterDescription
geometryGeometry
The geometry of interest.
collectionsList[str]
The geospatial collection names.
start_datestr
The start date of the search period in the YYYY-MM-DD format. The default value is 2020-01-01.
end_datestr
The end date of the search period in the YYYY-MM-DD format. The default value is 2020-01-30.
limitint
The number of full scenes on a results page. The maximum value is 500. The default value is 10.
max_cloudcoverOptional[int]
The maximum cloud coverage, in percentage.

search

Retrieves the full scenes matching the search parameters. Returns Union[geopandas.GeoDataFrame, dict].

ParameterDescription
search_parametersdict
Search parameters.
as_dataframebool
Determines how to return search results:
  • True: Returns GeoDataFrame.
  • False: Returns JSON.
The default value is True.

construct_order_parameters

Constructs an order form for a specific data product. Returns order.OrderParams.

ParameterDescription
data_product_idstr
The data product ID.
image_idstr
The scene ID.
aoiOptional[Geometry]
The order geometry.
tagsOptional[List[str]]
A list of tags that categorize the order.

To name orders, you can add a displayName attribute to the parameters.

Python 

    order_params = catalog.construct_order_parameters(
    data_product_id="c3de9ed8-f6e5-4bb5-a157-f6430ba756da",
    image_id="S2B_36SYE_20240229_0_L2A",
    aoi=geometry
)

# Adding a display name to the order
order_params["params"]["displayName"] = "My catalog order"

download_quicklooks

Downloads quicklooks, that is, low-resolution previews of full scenes returned in search results. Returns List[str].

ParameterDescription
image_idsList[str]
The scene IDs.
collectionstr
The geospatial collection name.
output_directoryUnion[str, pathlib.Path, None]
The file output directory. The default value is the current directory.

Learn more