Client API Usage¶

The following is a step-by-step guide that demonstrates how to use the Sen4CAP Python API in a Jupyter notebook.

The Python Sen4CAP client provides the following API methods:

• client.get_processes(): listing existing processes,
• client.get_process(): get the details about a process,
• client.execute_process(): executing a given process execution request,
• client.get_jobs(): observing the jobs resulting from a process execution,
• client.get_job(): getting a job's details,
• client.get_job_result(): getting a job's result, and finally
• client.dismiss_job(): cancelling a job.
• client.open_job_result(): open a result from a successful job.
• client.show_app(): open the client app UI.

In [1]:

import json
from pathlib import Path

from sen4cap_client.api import create_client

import json from pathlib import Path from sen4cap_client.api import create_client

Create a client instance¶

Important: Make sure you have already configured the client to run with the TAO Process API server. In a command shell run sen4cap-client configure. Leave all settings as suggested unless you are asked for your personal credentials. If this doesn't work for you, you can create a local config.json here. You could also use it to provide configuration overrides. For the possible configuration setting see here.

In [2]:

config_path = Path("config.json")
if config_path.exists():
    config = json.loads(config_path.read_text())
else:
    config = {}

config_path = Path("config.json") if config_path.exists(): config = json.loads(config_path.read_text()) else: config = {}

Create a Sen4CAP client instance with your configuration, if any.

In [4]:

client = create_client(**config)

client = create_client(**config)

Inspect the processes¶

List the currently available processes.

In [5]:

client.get_processes()

client.get_processes()

Out[5]:

{
  "links": [
    {
      "href": "/process/processes",
      "rel": "self",
      "type": "application/json"
    },
    {
      "href": "/process/processes/473",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/473/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/407",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/407/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/218",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/218/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/208",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/208/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/207",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/207/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/206",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/206/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/205",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/205/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/204",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/204/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/203",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/203/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/202",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/202/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/196",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/196/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/182",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/182/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/71",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/71/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    },
    {
      "href": "/process/processes/5",
      "rel": "self",
      "title": "Process description",
      "type": "application/json"
    },
    {
      "href": "/process/processes/5/execution",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute",
      "title": "Process execution",
      "type": "application/json"
    }
  ],
  "processes": [
    {
      "description": "Sen4CAP Marker database processor",
      "id": "473",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Sen4CAP Marker Database - 1782829198529",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP Tillage Detection Processor",
      "id": "407",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Sen4CAP Tillage Processor 5.0.0",
      "version": "1.0"
    },
    {
      "description": "Site Processing L3B NDVI Processor",
      "id": "218",
      "jobControlOptions": [
        "async-execute"
      ],
      "keywords": [
        "sen4cap",
        "L3B",
        "NDVI",
        "LAI",
        "FAPAR",
        "FCOVER",
        "NDWI"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "L3B AOI Indicators Processor 5.0.4",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP Crop Type Processor",
      "id": "208",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Sen4CAP Crop Type",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP Marker database processor",
      "id": "207",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Sen4CAP Marker Database",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP S1 Pre-Processor",
      "id": "206",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Sen4CAP S1 Pre-Processor",
      "version": "1.0"
    },
    {
      "description": "",
      "id": "205",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Bare Soil 5.0",
      "version": "1.0"
    },
    {
      "description": "",
      "id": "204",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Agricultural Practices 5.0",
      "version": "1.0"
    },
    {
      "description": "Parcel Heterogeneity Processor",
      "id": "203",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Parcel Heterogeneity 5.0",
      "version": "1.0"
    },
    {
      "id": "202",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "heterogeneityworkflow",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP Grassland Mowing Processor 5.0",
      "id": "196",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "Sen4CAP Grassland Mowing 5.0",
      "version": "1.0"
    },
    {
      "description": "",
      "id": "182",
      "jobControlOptions": [
        "async-execute"
      ],
      "keywords": [
        "Sen4CAP",
        "L3B"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "L3B MONO LAI Processor 5.0",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP Single L3B NDVI Processor",
      "id": "71",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "L3B MONO NDVI Processor 5.0",
      "version": "1.0"
    },
    {
      "description": "Sen4CAP L3B NDVI Processor ",
      "id": "5",
      "jobControlOptions": [
        "async-execute"
      ],
      "outputTransmission": [
        "value"
      ],
      "title": "L3BProcessor - NDVI",
      "version": "1.0"
    }
  ]
}

Get details about a selected process. Have a look at the inputs to see what parameters it accepts and what outputs it provides.

In [6]:

client.get_process(process_id="218")

client.get_process(process_id="218")

Out[6]:

{
  "description": "Site Processing L3B NDVI Processor",
  "id": "218",
  "inputs": {
    "472efeab-514a-4e15-9dba-d5812d653065": {
      "description": "End date",
      "schema": {
        "default": "",
        "description": "End date",
        "format": "date",
        "maxLength": 255,
        "minLength": 1,
        "title": "Parameter Schema",
        "type": "string"
      },
      "title": "End date",
      "x-ui-advanced": false,
      "x-ui-order": "2"
    },
    "691adc8e-9bba-4f42-86e2-ccd72189edc3": {
      "description": "L3B Indicator Name",
      "schema": {
        "default": "NDVI",
        "description": "L3B Indicator Name",
        "enum": [
          "NDVI",
          "LAI",
          "FAPAR",
          "FCOVER",
          "NDWI"
        ],
        "maxLength": 255,
        "minLength": 1,
        "title": "Parameter Schema",
        "type": "string",
        "x-ui-widget": "radio"
      },
      "title": "L3B Indicator Name",
      "x-ui-advanced": true,
      "x-ui-order": "3"
    },
    "bed1920e-51c0-406e-b22e-70d1f86d95d4": {
      "description": "Site extent",
      "schema": {
        "default": "",
        "description": "Site extent",
        "format": "wkt",
        "maxLength": 4096,
        "minLength": 1,
        "title": "Parameter Schema",
        "type": "string",
        "x-ui-widget": "map"
      },
      "title": "Site extent",
      "x-ui-advanced": false,
      "x-ui-order": "4"
    },
    "c30145a7-029c-4499-98bc-9903ca46531c": {
      "description": "Start date",
      "schema": {
        "default": "",
        "description": "Start date",
        "format": "date",
        "maxLength": 255,
        "minLength": 1,
        "title": "Parameter Schema",
        "type": "string"
      },
      "title": "Start date",
      "x-ui-advanced": false,
      "x-ui-order": "1"
    }
  },
  "outputs": {
    "db96d3e8-0243-48dc-ac9a-6470d2c39eb8": {
      "description": "stacitemsfile",
      "metadata": [
        {
          "title": "cardinality",
          "value": 1
        },
        {
          "title": "format",
          "value": "Unknown"
        },
        {
          "title": "sensor",
          "value": "Unknown"
        }
      ],
      "schema": {
        "maxLength": 0,
        "type": "string"
      },
      "title": "stacitemsfile"
    }
  },
  "title": "L3B AOI Indicators Processor 5.0.4",
  "version": "1.0"
}

Execute a process¶

Now that we know the inputs and outputs we can create a process request:

In [8]:

request = {
    'inputs': {
        'c30145a7-029c-4499-98bc-9903ca46531c': '2024-06-01',
        '472efeab-514a-4e15-9dba-d5812d653065': '2024-06-07',
        '691adc8e-9bba-4f42-86e2-ccd72189edc3': 'NDVI',
        'bed1920e-51c0-406e-b22e-70d1f86d95d4': 'POLYGON ((9.66 53.75,10.38 53.75,10.38 53.35,9.66 53.35,9.66 53.75))'
    },
    'outputs': {
        'db96d3e8-0243-48dc-ac9a-6470d2c39eb8': {
            "format": { "mediaType": "application/json" },
            "transmissionMode": "reference"
        }
    }
}

request = { 'inputs': { 'c30145a7-029c-4499-98bc-9903ca46531c': '2024-06-01', '472efeab-514a-4e15-9dba-d5812d653065': '2024-06-07', '691adc8e-9bba-4f42-86e2-ccd72189edc3': 'NDVI', 'bed1920e-51c0-406e-b22e-70d1f86d95d4': 'POLYGON ((9.66 53.75,10.38 53.75,10.38 53.35,9.66 53.35,9.66 53.75))' }, 'outputs': { 'db96d3e8-0243-48dc-ac9a-6470d2c39eb8': { "format": { "mediaType": "application/json" }, "transmissionMode": "reference" } } }

And execute a process. The execution is always asynchronously, which means, execute_process() will submit the request and immediately return a job onfo object.

In [9]:

client.execute_process(process_id="218", request=request)

client.execute_process(process_id="218", request=request)

Out[9]:

{'processID': 'L3B AOI Indicators Processor 5.0.4_virtual_2026-03-05T10:52:13',
 'type': 'process',
 'jobID': '647',
 'status': 'accepted',
 'created': '2026-06-29T14:45:06Z',
 'started': '2026-06-29T14:45:06Z',
 'updated': '2026-06-29T14:45:06Z',
 'progress': 0,
 'links': [{'href': 'http://localhost:8080/process/jobs/647',
   'rel': 'self',
   'type': 'application/json',
   'title': 'Job status'},
  {'href': 'http://localhost:8080/process/jobs/647/results',
   'rel': 'self',
   'type': 'application/json',
   'title': 'Job results (when status=successful)'}]}

Job management and getting the result¶

List all existing executions.

In [8]:

job_list = client.get_jobs()
job_list

job_list = client.get_jobs() job_list

Out[8]:

{
  "jobs": [
    {
      "created": "2026-06-29T14:45:06Z",
      "jobID": "647",
      "links": [
        {
          "href": "/process/jobs647",
          "rel": "self",
          "title": "Job status",
          "type": "application/json"
        },
        {
          "href": "/process/jobs647/results",
          "rel": "self",
          "title": "Job results (when status=successful)",
          "type": "application/json"
        }
      ],
      "processID": "L3B AOI Indicators Processor 5.0.4",
      "progress": 100,
      "started": "2026-06-29T14:45:06Z",
      "status": "successful",
      "updated": "2026-06-29T14:46:07Z"
    }
  ],
  "links": []
}

Observe our job from above:

In [10]:

client.get_job("647")

client.get_job("647")

Out[10]:

{
  "created": "2026-06-29T14:45:06Z",
  "jobID": "647",
  "links": [
    {
      "href": "/process/jobs/647",
      "rel": "self",
      "title": "Job status",
      "type": "application/json"
    },
    {
      "href": "/process/jobs/647/results",
      "rel": "self",
      "title": "Job results (when status=successful)",
      "type": "application/json"
    }
  ],
  "processID": "L3B AOI Indicators Processor 5.0.4",
  "progress": 100,
  "started": "2026-06-29T14:45:06Z",
  "status": "successful",
  "updated": "2026-06-29T14:46:07Z"
}

Once the status changes from running to successful, the results will be available. Get the job results:

In [12]:

job_results = client.get_job_results(job_id="647")
job_results

job_results = client.get_job_results(job_id="647") job_results

Out[12]:

{
  "db96d3e8-0243-48dc-ac9a-6470d2c39eb8": {
    "href": "http://sen4x.tao.c-s.ro:8082/collections/L3B_NDVI/items/S2AGRI_L3BNDVI_PRD_S23_20260629T093945_A20240607T102559_T32UNE",
    "type": "application/json"
  }
}

The job result is a link to a STAC item that contains the assets of this output. We open the asset SNDVI.

Note, we'll later add a function to inspect the available assets of an output.

In [8]:

data_array = client.open_job_result(job_id="647", asset_name="SNDVI")
data_array

data_array = client.open_job_result(job_id="647", asset_name="SNDVI") data_array

C:\Users\norma\AppData\Local\Temp\ipykernel_420\1436610364.py:1: UserWarning: An error occurred while getting process description for process ID 'L3B AOI Indicators Processor 5.0.4'
  data_array = client.open_job_result(job_id="647", asset_name="SNDVI")

Out[8]:

<xarray.DataArray (band: 1, y: 4520, x: 4834)> Size: 44MB
[21849680 values with dtype=int16]
Coordinates:
  * band         (band) int64 8B 1
  * y            (y) float64 36kB 5.957e+06 5.957e+06 ... 5.911e+06 5.911e+06
  * x            (x) float64 39kB 5.435e+05 5.435e+05 ... 5.918e+05 5.919e+05
    spatial_ref  int64 8B 0
Attributes:
    AREA_OR_POINT:  Area
    _FillValue:     -10000
    scale_factor:   1.0
    add_offset:     0.0

xarray.DataArray

• band: 1
• y: 4520
• x: 4834

• ...

  [21849680 values with dtype=int16]

• Coordinates: (4)
  • band
    (band)
    int64
    1

    array([1])

  • y
    (y)
    float64
    5.957e+06 5.957e+06 ... 5.911e+06

    array([5956595., 5956585., 5956575., ..., 5911425., 5911415., 5911405.],
          shape=(4520,))

  • x
    (x)
    float64
    5.435e+05 5.435e+05 ... 5.919e+05

    array([543525., 543535., 543545., ..., 591835., 591845., 591855.],
          shape=(4834,))

  • spatial_ref
    ()
    int64
    0

    crs_wkt :

    PROJCS["WGS 84 / UTM zone 32N",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",9],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","32632"]]

    semi_major_axis :

    6378137.0

    semi_minor_axis :

    6356752.314245179

    inverse_flattening :

    298.257223563

    reference_ellipsoid_name :

    WGS 84

    longitude_of_prime_meridian :

    0.0

    prime_meridian_name :

    Greenwich

    geographic_crs_name :

    WGS 84

    horizontal_datum_name :

    World Geodetic System 1984

    projected_crs_name :

    WGS 84 / UTM zone 32N

    grid_mapping_name :

    transverse_mercator

    latitude_of_projection_origin :

    0.0

    longitude_of_central_meridian :

    9.0

    false_easting :

    500000.0

    false_northing :

    0.0

    scale_factor_at_central_meridian :

    0.9996

    spatial_ref :

    PROJCS["WGS 84 / UTM zone 32N",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",9],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","32632"]]

    GeoTransform :

    543520.0 10.0 0.0 5956600.0 0.0 -10.0

    array(0)

• Attributes: (4)

  AREA_OR_POINT :

  Area

  _FillValue :

  -10000

  scale_factor :

  1.0

  add_offset :

  0.0

Visualize the result:

In [22]:

da.isel(band=0).plot.imshow(figsize=(10, 6), vmin=0, vmax=1000)

da.isel(band=0).plot.imshow(figsize=(10, 6), vmin=0, vmax=1000)

Matplotlib is building the font cache; this may take a moment.

Out[22]:

<matplotlib.image.AxesImage at 0x1ef8abd6120>

In [ ]: