Processing in SDK

Run processing jobs using the SDK.


Overview

Apply advanced processing to purchased geospatial data.

View repository

Class: ValidationError

A data class that represents errors encountered during job validation.

Attributes

AttributeDescription
messagestr
The message of the validation error.
namestr
The name of the validation error.

Class: JobStatus

An enumeration class that defines possible statuses for a job.

Constants

ConstantDescriptionValueTerminal status
CREATEDThe job has been created, but not yet accepted.createdNot terminal inline-icon-large
LICENSEDThe EULA has been accepted for this process. The job will move on to the validation stage.licensedNot terminal inline-icon-large
UNLICENSEDThe EULA hasn’t been accepted for this process. The job will fail. Accept the EULA through the console or the API and try again.unlicensedTerminal inline-icon-large
VALIDThe job has been validated.validNot terminal inline-icon-large
INVALIDThe job has failed validation. Fix your input parameters and try again.invalidTerminal inline-icon-large
ACCEPTEDThe job has been validated and accepted. The credits corresponding to the price are temporarily withheld until the job is completed.acceptedNot terminal inline-icon-large
REJECTEDThe job has been canceled due to an insufficient account balance. Top up your balance and try again.rejectedTerminal inline-icon-large
RUNNINGThe job is in progress.runningNot terminal inline-icon-large
SUCCESSFULThe job has been completed, and the results have been delivered to your storage.successfulNot terminal inline-icon-large
FAILEDThe job has failed.failedNot terminal inline-icon-large
CAPTUREDThe job has been completed, the results have been delivered to your storage, and any withheld credits have been deducted from your account balance.capturedTerminal inline-icon-large
RELEASEDThe job has failed. Any withheld credits have been released. Try again, and if the issue persists, contact support.releasedTerminal inline-icon-large

Class: JobSorting

A class that contains predefined sorting fields.

Attributes

AttributeDescription
process_idutils.SortingField
Sorts by process ID. The default order is ascending.
statusutils.SortingField
Sorts by job status. The default order is descending.
createdutils.SortingField
Sorts by creation date. The default order is descending.
creditsutils.SortingField
Sorts by credit consumption. The default order is descending.
Python
from itertools import islice
# Sort by cost, from the least expensive to the most expensive
jobs_sorted = up42.Job.all(sort_by=up42.JobSorting.credits.asc)
# Sort by creation date, from the most recent to the earliest
# jobs_sorted = up42.Job.all(sort_by=up42.JobSorting.created.desc)
# Sort by job status, in descending alphabetical order
# jobs_sorted = up42.Job.all(sort_by=up42.JobSorting.status.desc)
# Sort by process ID in ascending alphabetical order
# jobs_sorted = up42.Job.all(sort_by=up42.JobSorting.process_id.asc)
for job in islice(jobs_sorted, 0, 5): # Print first 5 results
print(f"- Job ID: {job.id}")
print(f" Price: {job.credits} credits")
print(f" Created at: {job.created}")
print(f" Status: {job.status.value}")
print(f" Started at: {job.started}")
print(f" Finished at: {job.finished or 'Not finished'}\n")

Class: Job

A data class that represents a job in the system.

Attributes

AttributeDescription
process_idstr
The process ID in a name format.
idstr
The job ID.
account_idstr
The account ID.
workspace_idOptional[str]
The workspace ID.
definitiondict
The inputs and other parameters used to execute the job.
statusJobStatus
The job status.
createddatetime.datetime
The timestamp when the job was created.
updateddatetime.datetime
The timestamp when the job was last updated.
collection_urlOptional[str] = None
The URL of the resulting STAC collection. Available only if the job status is terminal.
errorsOptional[List[ValidationError]]
Job errors. Available only if the job status is INVALID.
creditsOptional[int]
The job cost, in credits.
startedOptional[datetime.datetime]
The timestamp when the job was started.
finishedOptional[datetime.datetime]
The timestamp when the job was finished.
Python
# Select a job
job_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"
# Fetch job info
job = up42.Job.get(job_id=job_id)
# Define output
print(f"Job details for ID: {job.id}")
print(f"Process ID: {job.process_id}")
print(f"Definition: {job.definition}")
print(f"Collection URL: {job.collection_url}")
print(f"Price: {job.credits} credits")
print(f"Created at: {job.created}")
print(f"Status: {job.status.value}")
print(f"Started at: {job.started}")
print(f"Finished at: {job.finished or 'Not finished'}")

Properties

collection

Contains the STAC collection associated with the job. Available only if the job status is terminal. Returns pystac.Collection.

Python
# Select a job
job_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"
# Fetch job info
job = up42.Job.get(job_id=job_id)
# Define output
print(f"STAC collection ID: {job.collection.id}")

Methods

track

Tracks the job status by retrying until the status changes to a terminal status.

ParameterDescription
waitint
An interval between queries, in seconds. The default value is 60.
retriesint
The duration of querying. The default value is 60 * 24 * 3.
Python
# Select a job
job_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"
# Fetch job info
job = up42.Job.get(job_id=job_id)
print(f"Initial job status is '{job.status.value}'. Starting to track...\n")
# This will print a status log to your console every 20 seconds
# and will PAUSE the script here until the job is done
job.track(wait=20)
# This line will only run AFTER the job has finished tracking
print("\nTracking complete!")
print(f"The final job status is: {job.status.value}")

get

Fetches a specific job by its ID. Returns Job.

ParameterDescription
job_idstr
The job ID.
Python
# Select a job
job_id = "a0d443a2-41e8-4995-8b54-a5cc4c448227"
# Fetch job info
job = up42.Job.get(job_id=job_id)
# Define output
print(f"Job details for ID: {job.id}")
print(f"Price: {job.credits} credits")
print(f"Created at: {job.created}")
print(f"Status: {job.status.value}")
print(f"Started at: {job.started}")
print(f"Finished at: {job.finished or 'Not finished'}")

all

Retrieves all jobs, with optional filtering. Returns Iterator["Job"]. Use itertools.islice to offset and limit the results.

ParameterDescription
process_idOptional[List[str]]
Process IDs. Use to search for jobs running any of the provided processes.
workspace_idOptional[str]
The workspace ID. Use to get jobs from a specific workspace. Otherwise, jobs from the entire account will be returned.
statusOptional[List[JobStatus]]
Job statuses. Use to search for jobs with any of the provided statuses.
min_durationOptional[int]
The minimum duration of a job. Use to get jobs with runtimes greater than or equal to a specific number of seconds. Only jobs with the following statuses will be displayed:
  • RUNNING
  • SUCCESSFUL
  • CAPTURED
  • RELEASED
  • FAILED
max_durationOptional[int]
The maximum duration of a job. Use to get jobs with runtimes less than or equal to a specific number of seconds. Only jobs with the following statuses will be displayed:
  • RUNNING
  • SUCCESSFUL
  • CAPTURED
  • RELEASED
  • FAILED
sort_byOptional[utils.SortingField]
The results sorting method that arranges elements in ascending or descending order based on a chosen field. To view the list of possible values, see JobSorting.
Python
# Fetch all jobs, filtered by max duration and sorted by process ID
jobs = up42.Job.all(
max_duration=500,
sort_by=up42.JobSorting.process_id,
)
# Define output
for job in jobs:
print(f"- Job ID: {job.id}")
print(f" Process ID: {job.process_id}")
print(f" Price: {job.credits} credits")
print(f" Status: {job.status.value}")
print(f" Created at: {job.created}")
print(f" Started at: {job.started}")
print(f" Finished at: {job.finished or 'Not finished'}\n")

Class: Cost

A data class that compares the cost of a process with custom values. Supported comparison operators:

  • Greater than: <
  • Greater than or equal to: >
  • Less than: <=
  • Less than or equal to: =>

Attributes

AttributeDescription
strategystr
The pricing strategy used to calculate the cost.
creditsint
The process cost, in credits.
sizeOptional[int]
The size of the input STAC item.
unitOptional[str]
The unit of measurement used to calculate the size.
Python
from up42 import processing_templates
# Select an item
11 collapsed lines
stac_item_id = "68567134-27ad-7bd7-4b65-d61adb11fc78"
# Get the item from the STAC client
stac_client = up42.stac_client()
stac_item = next(stac_client.get_items(stac_item_id))
# Instanitate a DetectionTreesSpacept template
template = processing_templates.DetectionTreesSpacept(
title="Detect trees over UK",
item=stac_item,
)
# Verify that the template cost is less than or equal to 100 credits
acceptable_cost = 100
if template.cost <= acceptable_cost:
print(f"Template cost: {template.cost.credits} credits")
print(f"Template strategy: {template.cost.strategy}")
print(f"STAC item size: {template.cost.size}")
print(f"Unit of measurement: {template.cost.unit}")
else:
print(f"Template cost is higher than {acceptable cost} credits")

Class: JobTemplate

A class for job templates that define the process ID and input validation logic.

Attributes

AttributeDescription
process_idClassVar[str]
The process ID in a name format.
workspace_idUnion[str, base.WorkspaceId]
The workspace ID.
errorsset[ValidationError]
A list of errors populated if the job isn’t valid.

Properties

is_valid

Checks if the job is valid. Returns bool:

  • True: The job is valid.
  • False: The job isn’t valid.

Python
from up42 import processing_templates
# Select an item
stac_item_id = "68567134-27ad-7bd7-4b65-d61adb11fc78"
# Get the item from the STAC client
stac_client = up42.stac_client()
stac_item = next(stac_client.get_items(stac_item_id))
# Instanitate a DetectionTreesSpacept template
job = processing_templates.DetectionTreesSpacept(
title="Detect trees over UK",
item=stac_item,
)
# Assert that the job is valid, print errors if not
if not job.is_valid:
for error in job.errors:
print(f"{error}\n")

Methods

execute

Executes the job. Returns Job.

Python
from up42 import processing_templates
# Select an item
11 collapsed lines
stac_item_id = "68567134-27ad-7bd7-4b65-d61adb11fc78"
# Get the item from the STAC client
stac_client = up42.stac_client()
stac_item = next(stac_client.get_items(stac_item_id))
# Instanitate a DetectionTreesSpacept template
job_template = processing_templates.DetectionTreesSpacept(
title="Detect trees over UK",
item=stac_item,
)
# Execute the templated job
job = job_template.execute()
# Define output
print(f"Job details for ID: {job.id}")
print(f"Process ID: {job.process_id}")
print(f"Status: {job.status.value}")
print(f"Price: {job.credits or 'N/A'} credits")
print(f"Created at: {job.created}")

Class: SingleItemJobTemplate

A data class for the process templates that require one STAC item as input:

Atributes

AttributeDescription
titlestr
The title of the resulting objects: STAC item and STAC collection.
itempystac.Item
The STAC item to process.

Class: MultiItemJobTemplate

A data class for the process templates that require multiple STAC items as input:

Atributes

AttributeDescription
titlestr
The title of the resulting objects: STAC item and STAC collection.
itemsList[pystac.Item]
The STAC items to process.

Learn more


Last updated: