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.

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.

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

estimate_order

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

ParameterDescription
order_parametersorder.OrderParams
Order parameters.

Python 

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

tasking.estimate_order(
    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="/Users/max.mustermann/Desktop/aoi.geojson",
        tags=["project-7", "optical"],
    ),
)

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="/Users/max.mustermann/Desktop/aoi.geojson",
    ),
)

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.

Python 

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

# Tasking
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="/Users/max.mustermann/Desktop/aoi.geojson",
    tags=["project-7", "optical"],
)

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

# Catalog
catalog_order_parameters = catalog.construct_order_parameters(
    data_product_id="4f1b2f62-98df-4c74-81f4-5dce45deee99",
    image_id="a4c9e729-1b62-43be-82e4-4e02c31963dd",
    aoi="/Users/max.mustermann/Desktop/aoi.geojson",
)

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

Class: Catalog

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

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.
max_cloudcoverOptional[int]
The maximum cloud coverage, in percentage.

Python 

    catalog = up42.initialize_catalog()

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

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.

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",
        max_cloudcover=25,
    ),
    as_dataframe=False,
)

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.

Python 

    catalog = up42.initialize_catalog()

order_params = 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"],
)

# To name orders, you can add a `displayName` attribute to the parameters.
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.

Python 

    catalog = up42.initialize_catalog()

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

Learn more