Skip to content

Functionality overview

Structure

  • The Python SDK uses multiple classes, representing the hierarchical structure of UP42:

    • Catalog → Order → Asset
    • Tasking → Order → Asset
    • Storage → Asset
    • Project → Workflow → Job/JobCollection → JobTask

  • Each class object can spawn elements of one level below, for example:

    • project = up42.initialize_project()
    • workflow = project.create_workflow()
    • job = workflow.run_job()

Classes

Classes

up42 is the base library module imported to Python. It provides the elementary functionality that is not bound to a specific class of the UP42 structure. From up42 you can also initialize other classes, e.g. for using the catalog, storage etc.

To import the UP42 library: 

import up42

Authenticate with UP42 via 

up42.authenticate(
    project_id="your-project-ID",
    project_api_key="your-project-API-key"
)

To initialize any lower level functionality use e.g. 

catalog = up42.initialize_catalog()

project = up42.initialize_project()


Available functions, see also up42 reference:

  • .authenticate()
  • .create_webhook()
  • .draw_aoi()
  • .get_block_coverage()
  • .get_block_details()
  • .get_blocks()
  • .get_credits_balance()
  • .get_example_aoi()
  • .get_webhook_events()
  • .get_webhooks()
  • .initialize_asset()
  • .initialize_catalog()
  • .initialize_job()
  • .initialize_jobcollection()
  • .initialize_jobtask()
  • .initialize_order()
  • .initialize_project()
  • .initialize_storage()
  • .initialize_tasking()
  • .initialize_webhook()
  • .initialize_workflow()
  • .read_vector_file()
  • .validate_manifest()

The Tasking class enables access to the UP42 tasking functionality.

Use tasking: 

tasking = up42.initialize_tasking()


Available functions, see also Tasking reference:

  • .choose_feasibility()
  • .construct_order_parameters()
  • .decide_quotation()
  • .get_collections()
  • .get_data_product_schema()
  • .get_data_products()
  • .get_feasibility()
  • .get_quotations()
  • .place_order()

This class also inherits functions from the CatalogBase class.

The Catalog class enables access to the UP42 catalog functionality (data archive search & ordering).

Use catalog: 

catalog = up42.initialize_catalog()

This class also inherits functions from the CatalogBase class.


Available functions, see also Catalog reference:

  • .construct_order_parameters()
  • .construct_parameters()
  • .construct_search_parameters()
  • .download_quicklooks()
  • .estimate_order()
  • .get_collections()
  • .get_data_product_schema()
  • .get_data_products()
  • .map_quicklooks()
  • .place_order()
  • .plot_coverage()
  • .plot_quicklooks()
  • .search()

This class also inherits functions from the CatalogBase class.

The CatalogBase class is inherited by the Tasking and Catalog classes.

Available functions, see also CatalogBase reference:

  • .get_collections()
  • .get_data_product_schema()
  • .get_data_products()
  • .place_order()

The Order class enables you to place, inspect and get information on orders.

Use an existing order: 

order = up42.initialize_order(order_id="ea36dee9-fed6-457e-8400-2c20ebd30f44")


Available functions, see also Order reference:

  • .estimate()
  • .get_assets()
  • .place()
  • .track_status()
  • .info()
  • .status()
  • .order_details()
  • .is_fulfilled()

The Storage class enables access to the UP42 storage. You can list your assets and orders within an UP42 workspace.

Use the storage: 

storage = up42.initialize_storage()


Available functions, see also Storage reference:

  • .get_assets()
  • .get_orders()
  • .pystac_client()

The Asset class enables access to the UP42 assets in the storage. Assets are results of orders or results of jobs with download blocks.

Use an existing asset: 

asset = up42.initialize_asset(asset_id="8c2dfb4d-bd35-435f-8667-48aea0dce2da")


Available functions, see also Asset reference:

  • .download()
  • .download_stac_asset()
  • .update_metadata()
  • .info()
  • ._stac_search()
  • .stac_info()
  • .stac_items()

The Project is the top-level class of the UP42 hierarchy. With it you can create new workflows, query already existing workflows & jobs in the project and manage the project settings.

Create a new project on the UP42 Console website.

Use an existing project: 

up42.authenticate(project_id="uz92-8uo0-4dc9-ab1d-06d7ec1a5321",
                  project_api_key="9i7uec8a-45be-41ad-a50f-98bewb528b10")
project = up42.initialize_project()


Available functions, see also Project reference:

  • .create_workflow()
  • .get_jobs()
  • .get_project_settings()
  • .get_workflows()
  • .update_project_settings()
  • .info()
  • .max_concurrent_jobs()

The Workflow class lets you configure & run jobs and query existing jobs related to this workflow.

Create a new workflow: 

workflow = project.create_workflow(name="new_workflow")

Use an existing workflow: 

workflow = up42.initialize_workflow(workflow_id="7fb2ec8a-45be-41ad-a50f-98ba6b528b98")


Available functions, see also Workflow reference:

  • .add_workflow_tasks()
  • .construct_parameters()
  • .construct_parameters_parallel()
  • .delete()
  • .estimate_job()
  • .get_compatible_blocks()
  • .get_jobs()
  • .get_parameters_info()
  • .get_workflow_tasks()
  • .run_job()
  • .run_jobs_parallel()
  • .test_job()
  • .test_jobs_parallel()
  • .update_name()
  • .info()
  • .workflow_tasks()
  • .max_concurrent_jobs()

The Job class is the result of running a workflow. It lets you download, visualize and manipulate the results of the job, and keep track of the status or cancel a job while still running.

Run a new job: 

job = workflow.run_job(name="new_job", input_parameters={...})

Use an existing job: 

job = up42.initialize_job(job_id="de5806aa-5ef1-4dc9-ab1d-06d7ec1a5021")


Available functions, see also Job reference:

  • .cancel_job()
  • .download_quicklooks()
  • .download_results()
  • .get_credits()
  • .get_jobtasks()
  • .get_jobtasks_results_json()
  • .get_logs()
  • .get_results_json()
  • .map_quicklooks()
  • .map_results()
  • .plot_quicklooks()
  • .plot_results()
  • .track_status()
  • .upload_results_to_bucket()
  • .info()
  • .status()
  • .is_succeeded()

The JobTask class provides access to the result of a specific block in the workflow. Each job contains one or multiple JobTasks, one for each block.

Use an existing jobtask: 

jobtask = up42.initialize_jobtask(jobtask_id="3f772637-09aa-4164-bded-692fcd746d20",
                                  job_id="de5806aa-5ef1-4dc9-ab1d-06d7ec1a5021")


Available functions, see also JobTask reference:

  • .download_quicklooks()
  • .download_results()
  • .get_results_json()
  • .map_results()
  • .plot_quicklooks()
  • .plot_results()
  • .info()

The JobCollection class provides facilities for handling and downloading multiple jobs results as one object.

A jobcollection is created as the result of e.g. running multiple jobs in parallel: 

jobcollection = workflow.run_jobs_parallel()

Initialize a jobcollection from existing jobs: 

jobcollection = up42.initialize_jobcollection(job_ids=["12345", "6789"])


Available functions, see also JobCollection reference:

  • .apply()
  • .download_results()
  • .map_results()
  • .plot_results()
  • .info()
  • .status()

Contains UP42 webhooks functionality to set up a custom callback e.g. when an order is finished he webhook is triggered and an event notification is transmitted via HTTPS to a specific URL.

Also see the full webhook documentation.

Create a new webhook or query a existing ones via the up42 object, e.g. 

webhooks = up42.get_webhooks()

webhook = up42.initialize_webhook(webhook_id = "...")

The resulting Webhook object lets you modify, test or delete the specific webhook, e.g. 

webhook = webhook.trigger_test_event()


Available functions, see also Webhooks reference:

  • .delete()
  • .trigger_test_events()
  • .update()
  • .info()