Skip to content

🗃️ Functionality

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, e.g.

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

Functionality

A quick overview how the different class objects are created, used and which functionality they offer. More detail in the code reference.

Available Functionality

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_credits_history()
  • .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 Catalog class enables access to the UP42 catalog functionality (data archive search & ordering).

Use catalog: 

catalog = up42.initialize_catalog()


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

The Tasking class enables access to the UP42 tasking functionality.

Use tasking: 

tasking = up42.initialize_tasking()


Available functions, see also Tasking reference:

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

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 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()
  • .is_fulfilled()

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()
  • .update_metadata()
  • .info()
  • .stac_info()

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