Processing

Apply advanced processing to purchased geospatial data.

Step 1. Run a process

Step 2. Monitor processing jobs

Step 3. Download processing results

1. Select a process

   Processes are algorithms that you can apply to STAC items in your storage. There are two types of processes:

   • Enhancement processes that preprocess imagery to improve its visual quality.
   • Analytics processes that extract insights from imagery.

2. Accept the EULA

   If you want to run the chosen process for the first time, review and accept its end-user license agreement (EULA). If a EULA is updated, you need to re-accept it before creating your next job.

3. Prepare your request

   Call the Get processes endpoint to retrieve the name ID of the process you want to run. Call the Get a process endpoint with the process name ID as the path parameter and check the input response field for required and optional input parameters.

   Prepare your request body by following the structure specified in the corresponding process.

4. Validate your input

   To check the validity of your input, call the Validate input for a process endpoint with the name ID of the selected process as the path parameter. For the request body, use the prepared JSON.

   If a job has been validated, there will be a HTTP 200 OK response with no body.

   In case of any errors in the input, the returned error message will point to what caused it:

   JSON

   Copy

       {
     "errors": [
       {
         "name": "MissingPanchromaticAsset",
         "message": "The panchromatic band is missing."
       }
     ]
   }
   
     

5. Determine the cost

   To check the cost of a processing job before creating it, call the Determine the cost of a process endpoint with the name ID of the selected process as the path parameter and the following parameters in the request body:

   • A custom title
   • The STAC item you want to apply the algorithm to

   JSON

   Copy

       {
     "inputs": {
       "title": "Pansharpened imagery over UK",
       "item": "https://api.up42.com/v2/assets/stac/collections/21c0b14e-3434-4675-98d1-f225507ded99/items/23e4567-e89b-12d3-a456-426614174000"
     }
   }
   
     

   You’ll receive an overview of the overall UP42 credit amount that will be deducted from your credit balance if you decide to run the selected process:

   JSON

   Copy

       {
     "pricingStrategy": "area",
     "totalCredits": 63, // The process cost, in credits
     "totalSize": 15.8,
     "unit": "SQ_KM"
   }
   
     

6. Create a new processing job

   Credits will be deducted upon successful completion of the created processing job. The transaction can’t be reversed.

   To create a job, call the Run a process endpoint with the following parameters:

   • The name ID of the selected process as the path parameter
   • Your workspace ID as the query workspaceId parameter

   For example:

   For the request body, use the prepared JSON.

Get processing jobs as follows:

• Retrieve information about all jobs by calling the Get processing jobs endpoint.
• Retrieve information about a specific job by calling the Get a processing job with the job ID as the path parameter.

The most useful parameter for monitoring is job status.

Job statuses

Status	Description
created	The job has been created, but not yet accepted.
licensed	The EULA has been accepted for this process. The job will move on to the validation stage.
unlicensed	The EULA hasn’t been accepted for this process. The job will fail. Accept the EULA and try again.
valid	The job has been validated.
accepted	The job has been validated and accepted. The credits corresponding to the price are temporarily withheld until the job is completed.
invalid	The job has failed validation. Fix your input parameters and try again.
rejected	The job has been canceled due to an insufficient account balance. Top up your balance and try again.
running	The job is in progress.
successful	The job has been completed, and the results have been delivered to your storage.
captured	The job has been completed, the results have been delivered to your storage, and any withheld credits have been deducted from your account balance.
released	The job has failed. Any withheld credits have been released. Try again, and if the issue persists, contact support.
failed	The job has failed.

The following job statuses mean you can download processing results from storage:

• successful
• captured

1. Retrieve download links

   To get all assets from a specific job, call the Get specific STAC items endpoint with the following request body, using your job ID:

   JSON

   Copy

       {
     "filter": {
       "args": [
         {
           "property": "job_id"
         },
         "68567134-27ad-7bd7-4b65-d61adb11fc78" // Replace with your job ID
       ],
       "op": "="
     }
   }
   
     

   The response will contain your job results listed in the features.assets object. Retrieve the download links of the STAC assets you want to access.

   JSON

   Copy

       {
     "links": [], // Additional links
     "type": "FeatureCollection",
     "features": [
       {
         "assets": {
           "072e661d_pan_68567134-27ad-7bd7-4b65-d61adb11fc78.tiff": {
             "href": "https://api.up42.com/v2/assets/a0d443a2-41e8-4995", // The download link with an asset ID to use later
             "title": "Pansharpened multispectral data",
             "type": "image/tiff; application=geotiff; profile=cloud-optimized",
             "roles": ["pansharpened", "data", "multispectral"]
           }
         },
         // Other parameters
         "type": "Feature",
         "stac_version": "1.0.0"
       }
     ]
   }
   
     

2. Download assets

   To download these assets one by one, call the Download an asset endpoint with the retrieved download link. For example:

   If the request is successful, you’ll receive the requested asset as a response.

   You can also generate a signed URL to download an asset without authentication. Call the Create a download URL endpoint with the asset ID as the path parameter. The generated URL is valid for 5 minutes and can be shared.