API Reference#
Client#
- class vso_api_client.Client(api_url: str = 'https://ap.icare.univ-lille.fr/vso/v1', auth_client: ~icare_auth_clients.clients.DataTerraAuthClient = <icare_auth_clients.clients.DataTerraAuthClient object>)[source]#
Bases:
object- property api_url#
- cancel_job(job_id: UUID, access_token: str | None = None) dict[source]#
Cancel a running or pending job.
- Parameters:
job_id – Unique identifier of the job to cancel.
access_token – Optional authentication token. If not provided, client will try to obtain one or prompt the user to login.
- Returns:
Dictionary confirming the cancellation status and job details.
- get_has_job_ended(job_id: UUID) dict[source]#
Check if a job has completed (successfully or failed).
- Parameters:
job_id – Unique identifier of the job to check completion status for.
- Returns:
Dictionary indicating whether the job has ended and its completion status.
- get_job(job_id: UUID) dict[source]#
Retrieve detailed information for a specific job.
- Parameters:
job_id – Unique identifier of the job to retrieve.
- Returns:
Dictionary containing comprehensive job details including status, parameters, and metadata.
- get_job_logs(job_id: UUID, level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO', after: datetime | None = None, before: datetime | None = None) dict[source]#
Retrieve log entries for a specific job with optional filtering.
- Parameters:
job_id – Unique identifier of the job to retrieve logs for.
level – Minimum log level to retrieve (e.g., ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’).
after – Optional datetime filter to get logs after this timestamp.
before – Optional datetime filter to get logs before this timestamp.
- Returns:
List of log entry dictionaries with timestamp, level, and message.
- get_job_progress(job_id: UUID) dict[source]#
Get the current progress of a running job.
- Parameters:
job_id – Unique identifier of the job to check progress for.
- Returns:
Dictionary containing progress information (e.g., percentage completed, current step).
- get_job_result(job_id: UUID) dict[source]#
Download the result files for a successfully completed job.
- Parameters:
job_id – Unique identifier of the completed job to download results from.
- Returns:
Dictionary containing download information or file content for the job results.
- get_job_status(job_id: UUID) dict[source]#
Get the current status of a specific job.
- Parameters:
job_id – Unique identifier of the job to check status for.
- Returns:
Dictionary containing job status information (e.g., ‘pending’, ‘running’, ‘completed’, ‘failed’).
- get_jobs(workflow: str | None = None, completed: bool | None = None, limit: int = 100, offset: int = 0) list[dict][source]#
Retrieve a list of jobs with optional filtering by workflow type and completion status.
- Parameters:
workflow – Optional workflow type to filter jobs (e.g., ‘sentinel1-insar’).
completed – If True, return only completed jobs; if False, return only pending jobs. All jobs are returned if None.
limit – Maximum number of jobs to retrieve in paginated result.
offset – Offset to determine the number of jobs to skip in paginated result.
- Returns:
List of job dictionaries containing job details.
- get_workflow(workflow: str) dict[source]#
Retrieve detailed information about a specific workflow including parameter schema and examples.
- Parameters:
workflow – The workflow type to get information for (e.g., ‘sentinel1-insar’).
- Returns:
Dictionary containing detailed workflow information including schema and examples.
- get_workflow_examples(workflow: str) dict[str, dict][source]#
Retrieve example parameters for a specific workflow type from the API.
- Parameters:
workflow – The workflow type to get examples for (e.g., ‘sentinel1-insar’).
- Returns:
Dictionary containing example parameter sets for the workflow.
- get_workflow_parameters_schema(workflow: str) dict[source]#
Retrieve JSON schema for a specific workflow’s parameters.
- Parameters:
workflow – The workflow type to get schema for (e.g., ‘sentinel1-insar’).
- Returns:
Dictionary containing the JSON schema for workflow parameters.
- get_workflows() dict[source]#
Retrieve a list of all supported workflows.
- Returns:
Dictionary containing list of workflows with their names and descriptions.
- submit_job(workflow: str, job_parameters: dict | str | PathLike, access_token: str | None = None) dict[source]#
Submit a new job for processing with the specified workflow and parameters.
- Parameters:
workflow – The type of workflow to execute (e.g., ‘sentinel1-insar’).
job_parameters – Dictionary or json file containing all required parameters for the selected workflow.
access_token – Optional authentication token. If not provided, client will try to obtain one or prompt the user to login.
- Returns:
Dictionary containing submitted job details including job ID and initial status.
Exceptions#
- class vso_api_client.exceptions.APIError(status_code: int, message: str)[source]#
Bases:
ExceptionBase exception for all VSO API errors.
This exception is raised for general API errors that don’t fit into more specific error categories.
- Parameters:
status_code – HTTP status code returned by the API.
message – Error message describing the issue.
- class vso_api_client.exceptions.InputValidationError(status_code: int, message: str)[source]#
Bases:
APIErrorException raised for input validation errors (HTTP 422).
This exception is raised when the API returns a 422 status code, indicating that the request parameters were invalid.
- class vso_api_client.exceptions.AuthenticationError(status_code: int, message: str)[source]#
Bases:
APIErrorException raised for authentication errors (HTTP 401/403).
This exception is raised when the API returns a 401 or 403 status code, indicating authentication or authorization failures.
Bases:
APIErrorException raised when the service is unavailable (HTTP 503).
This exception is raised when the API returns a 503 status code, indicating that the service is temporarily unavailable.