Client API¶

The Python API client allows for

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.

In the following, we visit all the features by example.

The client expects a running server that conforms to the OGC API - Processes: Part 1, Version 1.0. If you don't have one available, you can also run the project's server with a test configuration:

s2gos-server run -- s2gos_server.services.testing:service

or

s2gos-server run -- wraptile.services.local.testing:service

In [1]:

Copied!

from s2gos_client import Client
from gavicore.models import ProcessRequest
from s2gos_client import Client
from gavicore.models import ProcessRequest

In [2]:

Copied!

client = Client()
client
client = Client()
client

Out[2]:

{
  "api_key": null,
  "api_key_header": "X-API-Key",
  "api_url": "http://localhost:8008/",
  "auth_type": "none",
  "auth_url": null,
  "password": null,
  "token": null,
  "token_header": "X-Auth-Token",
  "use_bearer": false,
  "username": null
}

In [3]:

Copied!

client.get_capabilities()
client.get_capabilities()

Out[3]:

{
  "description": "Local DTE-S2GOS process server for testing",
  "links": [
    {
      "href": "http://localhost:8008/",
      "hreflang": "en",
      "rel": "self",
      "title": "get_capabilities",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/openapi.json",
      "hreflang": "en",
      "rel": "service",
      "title": "openapi",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/docs",
      "hreflang": "en",
      "rel": "service",
      "title": "swagger_ui_html",
      "type": "text/html"
    },
    {
      "href": "http://localhost:8008/docs/oauth2-redirect",
      "hreflang": "en",
      "rel": "service",
      "title": "swagger_ui_redirect",
      "type": "text/html"
    },
    {
      "href": "http://localhost:8008/redoc",
      "hreflang": "en",
      "rel": "service",
      "title": "redoc_html",
      "type": "text/html"
    },
    {
      "href": "http://localhost:8008/",
      "hreflang": "en",
      "rel": "service",
      "title": "get_capabilities",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/conformance",
      "hreflang": "en",
      "rel": "service",
      "title": "get_conformance",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/processes",
      "hreflang": "en",
      "rel": "service",
      "title": "get_processes",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/processes/{processID}",
      "hreflang": "en",
      "rel": "service",
      "title": "get_process",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/processes/{processID}/execution",
      "hreflang": "en",
      "rel": "service",
      "title": "execute_process",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/jobs",
      "hreflang": "en",
      "rel": "service",
      "title": "get_jobs",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/jobs/{jobId}",
      "hreflang": "en",
      "rel": "service",
      "title": "get_job",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/jobs/{jobId}",
      "hreflang": "en",
      "rel": "service",
      "title": "dismiss_job",
      "type": "application/json"
    },
    {
      "href": "http://localhost:8008/jobs/{jobId}/results",
      "hreflang": "en",
      "rel": "service",
      "title": "get_job_results",
      "type": "application/json"
    }
  ],
  "title": "S2GOS Test-Server"
}

In [4]:

Copied!

client.get_conformance()
client.get_conformance()

Out[4]:

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/ogc-process-description",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/json",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/job-list",
    "http://www.opengis.net/spec/ogcapi-processes-1/1.0/conf/dismiss"
  ]
}

In [5]:

Copied!

client.get_processes()
client.get_processes()

Out[5]:

{
  "links": [
    {
      "href": "http://localhost:8008/processes",
      "hreflang": "en",
      "rel": "self",
      "title": "get_processes",
      "type": "application/json"
    }
  ],
  "processes": [
    {
      "description": "Generate 3D scene for MTR demo with seasonal variations.\n\nThis processor:\n1. Creates a scene generation configuration based on season/month\n2. Immediately runs the generation pipeline\n3. Returns path to the generated scene description YAML\n\nThe scene includes:\n- PNP location with 10km target area\n- Seasonal vegetation (summer/winter variants)\n- Heterogeneous atmosphere with aerosol layer\n- Tower XML scene at fixed location\n- Optional snow cover (June only)\n\nArgs:\n    month: Month for simulation (controls seasonal variations)\n    random_seed: Random seed for reproducible vegetation placement\n    config_output_dir: Optional directory for generation config JSON\n    scene_output_dir: Optional directory for scene description YAML\n\nReturns:\n    Path to generated scene description YAML file, or None if validation fails",
      "id": "mtr_demo_generation",
      "version": "0.0.0"
    },
    {
      "description": "Run simulation for MTR demo with configurable observation types.\n\nThis processor:\n1. Creates a simulation configuration based on observation type\n2. Immediately runs the simulation\n3. Returns path to the simulation output directory\n\nSupported observation types:\n- CHIME: Hyperspectral satellite sensor\n- MSI: Sentinel-2 multispectral sensor (configurable bands)\n- HYPSTAR: Ground-based hyperspectral sensor with HCRF processing\n- RGB_CAMERA: Perspective camera viewing tower from configurable position\n- SATELLITE_HDRF: [PLACEHOLDER - To be implemented]\n\nArgs:\n    scene_description_path: Path to scene YAML from generation step\n    month: Month for simulation (determines observation date)\n    hour_utc: Hour of observation in UTC\n    observation: Observation type configuration\n    spp: Samples per pixel for Monte Carlo simulation\n    config_output_dir: Optional directory for simulation config JSON\n    simulation_output_dir: Optional directory for simulation outputs\n\nReturns:\n    Path to simulation output directory, or None if observation type\n    is not yet implemented or simulation fails",
      "id": "mtr_demo_simulation",
      "version": "0.0.0"
    }
  ]
}

In [7]:

Copied!

client.get_process(process_id="mtr_demo_generation")
client.get_process(process_id="mtr_demo_generation")

Out[7]:

{
  "description": "Generate 3D scene for MTR demo with seasonal variations.\n\nThis processor:\n1. Creates a scene generation configuration based on season/month\n2. Immediately runs the generation pipeline\n3. Returns path to the generated scene description YAML\n\nThe scene includes:\n- PNP location with 10km target area\n- Seasonal vegetation (summer/winter variants)\n- Heterogeneous atmosphere with aerosol layer\n- Tower XML scene at fixed location\n- Optional snow cover (June only)\n\nArgs:\n    month: Month for simulation (controls seasonal variations)\n    random_seed: Random seed for reproducible vegetation placement\n    config_output_dir: Optional directory for generation config JSON\n    scene_output_dir: Optional directory for scene description YAML\n\nReturns:\n    Path to generated scene description YAML file, or None if validation fails",
  "id": "mtr_demo_generation",
  "inputs": {
    "config_output_dir": {
      "description": "Path configuration that preserves credential reference through serialization.\n\nThis model allows paths to reference credentials by ID rather than embedding\nactual credentials. When serialized to JSON, only the path value and credential_id\nare stored (no actual credentials). When deserialized, credentials are resolved\nfrom the credential provider (environment variables or .secrets.yaml).\n\nAttributes:\n    value: The actual path/URI\n    cid: Optional reference to a Credential ID in the credential provider\n\nExample:\n    # With credentials\n    path = PathRef(\n        path=\"https://data.earthdatahub.destine.eu/data.zarr\",\n        cid=\"earthdatahub\"\n    )\n\n    # Without credentials (public or local path)\n    path = PathRef(\"/local/path/data.zarr\")\n\n    # Access the authenticated UPath\n    upath = path.upath",
      "minOccurs": 0,
      "schema": {
        "nullable": true,
        "properties": {
          "cid": {
            "description": "Credential ID",
            "nullable": true,
            "title": "Cid",
            "type": "string"
          },
          "value": {
            "description": "Full path URI",
            "title": "Value",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "title": "PathRef"
    },
    "month": {
      "description": "Month selection for MTR demo (limited to solstice dates).",
      "minOccurs": 0,
      "schema": {
        "default": "december",
        "enum": [
          "december",
          "june"
        ],
        "type": "string"
      },
      "title": "Month"
    },
    "random_seed": {
      "description": "RNG seed for vegetation placement",
      "minOccurs": 0,
      "schema": {
        "default": 13,
        "type": "integer"
      },
      "title": "Random Seed"
    },
    "scene_output_dir": {
      "description": "Path configuration that preserves credential reference through serialization.\n\nThis model allows paths to reference credentials by ID rather than embedding\nactual credentials. When serialized to JSON, only the path value and credential_id\nare stored (no actual credentials). When deserialized, credentials are resolved\nfrom the credential provider (environment variables or .secrets.yaml).\n\nAttributes:\n    value: The actual path/URI\n    cid: Optional reference to a Credential ID in the credential provider\n\nExample:\n    # With credentials\n    path = PathRef(\n        path=\"https://data.earthdatahub.destine.eu/data.zarr\",\n        cid=\"earthdatahub\"\n    )\n\n    # Without credentials (public or local path)\n    path = PathRef(\"/local/path/data.zarr\")\n\n    # Access the authenticated UPath\n    upath = path.upath",
      "minOccurs": 0,
      "schema": {
        "nullable": true,
        "properties": {
          "cid": {
            "description": "Credential ID",
            "nullable": true,
            "title": "Cid",
            "type": "string"
          },
          "value": {
            "description": "Full path URI",
            "title": "Value",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "title": "PathRef"
    }
  },
  "outputs": {
    "return_value": {
      "description": "Path configuration that preserves credential reference through serialization.\n\nThis model allows paths to reference credentials by ID rather than embedding\nactual credentials. When serialized to JSON, only the path value and credential_id\nare stored (no actual credentials). When deserialized, credentials are resolved\nfrom the credential provider (environment variables or .secrets.yaml).\n\nAttributes:\n    value: The actual path/URI\n    cid: Optional reference to a Credential ID in the credential provider\n\nExample:\n    # With credentials\n    path = PathRef(\n        path=\"https://data.earthdatahub.destine.eu/data.zarr\",\n        cid=\"earthdatahub\"\n    )\n\n    # Without credentials (public or local path)\n    path = PathRef(\"/local/path/data.zarr\")\n\n    # Access the authenticated UPath\n    upath = path.upath",
      "schema": {
        "nullable": true,
        "properties": {
          "cid": {
            "description": "Credential ID",
            "nullable": true,
            "title": "Cid",
            "type": "string"
          },
          "value": {
            "description": "Full path URI",
            "title": "Value",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "title": "PathRef"
    }
  },
  "version": "0.0.0"
}

In [ ]:

Copied!

client.get_jobs()
client.get_jobs()

In [ ]:

Copied!

client.execute_process(process_id="sleep_a_while", request=ProcessRequest(duration=2))
client.execute_process(process_id="sleep_a_while", request=ProcessRequest(duration=2))

In [ ]:

Copied!

client.execute_process(process_id="sleep_a_while", request={"fail": True})
client.execute_process(process_id="sleep_a_while", request={"fail": True})

In [ ]:

Copied!

client.execute_process(process_id="primes_between", request={})
client.execute_process(process_id="primes_between", request={})

In [ ]:

Copied!

client.get_jobs()
client.get_jobs()

In [ ]:

Copied!

client.get_job("job_2")
client.get_job("job_2")

In [ ]:

Copied!

# client.get_job_results("job_1")
# client.get_job_results("job_1")

In [ ]:

Copied!

for job in client.get_jobs().jobs:
    client.dismiss_job(job.jobID)
for job in client.get_jobs().jobs:
    client.dismiss_job(job.jobID)

In [ ]:

Copied!

client.get_jobs()
client.get_jobs()

In [ ]: