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