cads_api_client.ApiClient

class cads_api_client.ApiClient

A client to interact with the CADS API.

Parameters:

• url (str or None, default: None) – API URL. If None, infer from CADS_API_URL or CADS_API_RC.

• key (str or None, default: None) – API Key. If None, infer from CADS_API_KEY or CADS_API_RC.

• verify (bool, default: True) – Whether to verify the TLS certificate at the remote end.

• timeout (float or tuple[float,float], default: 60) – How many seconds to wait for the server to send data, as a float, or a (connect, read) tuple.

• progress (bool, default: True) – Whether to display the progress bar during download.

• cleanup (bool, default: False) – Whether to delete requests after completion.

• sleep_max (float, default: 120) – Maximum time to wait (in seconds) while checking for a status change.

• retry_after (float, default: 120) – Time to wait (in seconds) between retries.

• maximum_tries (int, default: 500) – Maximum number of retries.

• session (requests.Session) – Requests session.

accept_licence(licence_id, revision)

Accept a licence.

Parameters:

• licence_id (str) – Licence ID.

• revision (int) – Licence revision number.

Returns:

Content of the response.

Return type:

dict[str,Any]

apply_constraints(collection_id, **request)

Apply constraints to the parameters in a request.

Parameters:

• collection_id (str) – Collection ID (e.g., "projections-cmip6").

• **request (Any) – Request parameters.

Returns:

Dictionary of valid values.

Return type:

dict[str,Any]

check_authentication()

Verify authentication.

Returns:

Content of the response.

Return type:

dict[str,Any]

Raises:

requests.HTTPError – If the authentication fails.

download_results(request_uid, target=None)

Download the results of a request.

Parameters:

• request_uid (str) – Request UID.

• target (str or None) – Target path. If None, download to the working directory.

Returns:

Path to the retrieved file.

Return type:

str

estimate_costs(collection_id, **request)

Estimate costs of the parameters in a request.

Parameters:

• collection_id (str) – Collection ID (e.g., "projections-cmip6").

• **request (Any) – Request parameters.

Returns:

Dictionary of estimated costs.

Return type:

dict[str,Any]

get_accepted_licences(scope=None)

Retrieve accepted licences.

Parameters:

scope ({None, 'all', 'dataset', 'portal'}) – Licence scope.

Returns:

List of dictionaries with license information.

Return type:

list[dict[str,Any]]

get_collection(collection_id)

Retrieve a catalogue collection.

Parameters:

collection_id (str) – Collection ID (e.g., "projections-cmip6").

Return type:

cads_api_client.Collection

get_collections(limit=None, sortby=None, query=None, keywords=None)

Retrieve catalogue collections.

Parameters:

• limit (int | None) – Number of processes per page.

• sortby ({None, 'id', 'relevance', 'title', 'update'}) – Field to sort results by.

• query (str or None) – Full-text search query.

• keywords (list[str] or None) – Filter by keywords.

Return type:

cads_api_client.Collections

get_jobs(limit=None, sortby=None, status=None)

Retrieve submitted jobs.

Parameters:

• limit (int or None) – Number of processes per page.

• sortby ({None, 'created', '-created'}) – Field to sort results by.

• status ({None, 'accepted', 'running', 'successful', 'failed'}) – Status of the results.

Return type:

cads_api_client.Jobs

get_licences(scope=None)

Retrieve licences.

Parameters:

scope ({None, 'all', 'dataset', 'portal'}) – Licence scope.

Returns:

List of dictionaries with license information.

Return type:

list[dict[str,Any]]

get_process(collection_id)

Retrieve a process.

Parameters:

collection_id (str) – Collection ID (e.g., "projections-cmip6").

Return type:

cads_api_client.Process

get_processes(limit=None, sortby=None)

Retrieve available processes.

Parameters:

• limit (int or None) – Number of processes per page.

• sortby ({None, 'id', '-id'}) – Field to sort results by.

Return type:

cads_api_client.Processes

get_remote(request_uid)

Retrieve the remote object of a request.

Parameters:

request_uid (str) – Request UID.

Return type:

cads_api_client.Remote

get_results(request_uid)

Retrieve the results of a request.

Parameters:

request_uid (str) – Request UID.

Return type:

cads_api_client.Results

retrieve(collection_id, target=None, **request)

Submit a request and retrieve the results.

Parameters:

• collection_id (str) – Collection ID (e.g., "projections-cmip6").

• target (str or None) – Target path. If None, download to the working directory.

• **request (Any) – Request parameters.

Returns:

Path to the retrieved file.

Return type:

str

submit(collection_id, **request)

Submit a request.

Parameters:

• collection_id (str) – Collection ID (e.g., "projections-cmip6").

• **request (Any) – Request parameters.

Return type:

cads_api_client.Remote

submit_and_wait_on_results(collection_id, **request)

Submit a request and wait for the results to be ready.

Parameters:

• collection_id (str) – Collection ID (e.g., "projections-cmip6").

• **request (Any) – Request parameters.

Return type:

cads_api_client.Results