Processing API

1. Select a process

   Review the specifications of processes and select a process you want to run. Processes can be divided into two categories:

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

   To get a list of all processes, call the Get processes endpoint. Select the process you want to proceed with and retrieve its name ID.

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.

Search for data in one of the following ways:

• Using a simple search, if you already know which item you want to use.
• Using a detailed search, if you want to find a compatible item.

You can only process items that come from a supported collection and that are added to storage starting in 2023.

1. Prepare your request

   Call the Get a process endpoint with the process name ID as the path parameter and check the inputs object for required and optional input parameters.

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

   For example, this is Coregistration’s schema:

   1
   {
   2
     "id": "coregistration-simularity",
   3
     "title": "Coregistration",
   4
     "description": "An algorithm that improves the positional accuracy of imagery against a reference.",
   5
     <...>
   6
     "inputs": {
   7
       "title": {
   8
         "title": "Title",
   9
         "description": "The title of the produced STAC objects.",
   10
         "minOccurs": 1,
   11
         "maxOccurs": 1,
   12
         "schema": {
   13
           "type": "string",
   14
           "minLength": 1,
   15
           "maxLength": 250
   16
         }
   17
       },
   18
       "sourceItem": {
   19
         "title": "Source STAC item",
   20
         "description": "A unique identifier of the source item to be coregistered.",
   21
         "minOccurs": 1,
   22
         "maxOccurs": 1,
   23
         "schema": {
   24
           "type": "string",
   25
           "format": "uri",
   26
           "description": "The path to a STAC item in the '/v2/assets/stac/collections/{collection-id}/items/{item-id}' format."
   27
         }
   28
       },
   29
       "referenceItem": {
   30
         "title": "Reference STAC item",
   31
         "description": "A unique identifier of the reference item.",
   32
         "minOccurs": 1,
   33
         "maxOccurs": 1,
   34
         "schema": {
   35
           "type": "string",
   36
           "format": "uri",
   37
           "description": "The path to a STAC item in the '/v2/assets/stac/collections/{collection-id}/items/{item-id}' format."
   38
         }
   39
       }
   40
       <...>
   41
     }
   42
   }

   The parameters in the inputs object need to be specified. For the coregistration-simularity process, these are the following parameters:

   • Title
   • Source item
   • Reference item

   A sample request body for this process:

   1
   {
   2
     "inputs": {
   3
       "title": "Coregistering imagery over Berlin",
   4
       "sourceItem": "https://api.up42.com/v2/assets/stac/collections/<...>/items/<...>",
   5
       "referenceItem": "https://api.up42.com/v2/assets/stac/collections/<...>/items/<...>"
   6
     }
   7
   }

2. 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:

   1
   {
   2
     "errors": [
   3
       {
   4
         "name": "MissingPanchromaticAsset",
   5
         "message": "The panchromatic band is missing."
   6
       }
   7
     ]
   8
   }

3. 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

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

   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:

   1
   {
   2
     "pricingStrategy": "area",
   3
     "totalCredits": 63, // The process cost, in credits
   4
     "totalSize": 15.8,
   5
     "unit": "SQ_KM"
   6
   }

4. 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
   HTTP Shell

   POST /v2/processing/processes/<process-name>/execution?workspaceId=<your-workspace-id> HTTP/1.1
   Host: api.up42.com
   Authorization: Bearer {token}

   curl --location 'https://api.up42.com/v2/processing/processes/<process-name>/execution?workspaceId=<your-workspace-id>' \
   --header 'Authorization: Bearer {token}

   For the request body, use the prepared JSON.

1. Check job status

   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.

   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

2. Retrieve assets’ 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:

   1
   {
   2
     "filter": {
   3
       "args": [
   4
         {
   5
           "property": "job_id"
   6
         },
   7
         "68567134-27ad-7bd7-4b65-d61adb11fc78" // Replace with your job ID
   8
       ],
   9
       "op": "="
   10
     }
   11
   }

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

   1
   {
   2
     "links": [], // Additional links
   3
     "type": "FeatureCollection",
   4
     "features": [
   5
       {
   6
         "assets": {
   7
           "072e661d_pan_68567134-27ad-7bd7-4b65-d61adb11fc78.tiff": {
   8
             "href": "https://api.up42.com/v2/assets/ea36dee9-fed6-457e-8400-2c20ebd30f44", // The asset ID in this example is ea36dee9-fed6-457e-8400-2c20ebd30f44
   9
             "title": "Pansharpened multispectral data",
   10
             "type": "image/tiff; application=geotiff; profile=cloud-optimized",
   11
             "roles": ["pansharpened", "data", "multispectral"]
   12
           }
   13
         },
   14
         // Other parameters
   15
         "type": "Feature",
   16
         "stac_version": "1.0.0"
   17
       }
   18
     ]
   19
   }

   You can generate a pre-signed URL to download an asset without authentication by calling 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. The URL will have the following format:

   1
   {
   2
     "url": "https://storage.googleapis.com/user-storage-interstellar-prod/assets/<...>"
   3
   }