API

OceanOpsClient

class OceanOpsClient.OceanOpsClient.OceanOpsClient(settings: Settings | None = None)

Bases: object

Client for interacting with the OceanOPS API.

Provides methods for read-only data retrieval and authenticated data submission. Supports JSON schema validation of OceanOPS “passport” files.

Variables:

• BASE_URL – Base URL for OceanOPS API endpoints.

• DEFAULT_SCHEMA_URL – URL to the default passport JSON schema.

• settings (Optional[Settings]) – Optional credentials/settings.

BASE_URL = 'https://www.ocean-ops.org/api/data'

DEFAULT_SCHEMA_URL = 'https://www.ocean-ops.org/passports/examples/a-passport-input.schema.json'

classmethod from_credentials(key_id: str, token: str) → OceanOpsClient

Create an OceanOps client from explicit credentials.

Parameters:

• key_id (str) – API key ID.

• token (str) – API key token.

Returns:

Instance of OceanOps client with credentials.

Return type:

OceanOps

classmethod from_env(env_file: str | None = None) → OceanOpsClient

Create an OceanOps client from environment variables or a .env file.

Parameters:

env_file (Optional[str]) – Path to a .env file. If None, uses default environment variables.

Returns:

Instance of OceanOps client. If credentials cannot be loaded, returns a read-only client.

Return type:

OceanOps

get_platform(ptfWigosId: str) → Dict[str, Any]

Retrieve platform information from OceanOPS using a WIGOS ID.

Parameters:

ptfWigosId (str) – Platform WIGOS ID.

Returns:

JSON response from the OceanOPS API.

Return type:

Dict[str, Any]

Raises:

• ValueError – If ptfWigosId is not provided.

• requests.HTTPError – If the API request fails.

post_get_id(program: str, start_date: str, model: str, batch_status: str, longitude: float, latitude: float) → Dict[str, Any]

Request a single platform identifier from OceanOPS.

Parameters:

• program – Program name (e.g., “Argo CANADA”)

• start_date – Deployment/start date (ISO format)

• model – Platform model (e.g., “APEX”)

• batch_status – Batch status (e.g., “IN STOCK”)

• longitude – Deployment longitude

• latitude – Deployment latitude

Returns:

Result for the requested identifier

Return type:

Dict[str, Any]

Raises:

RuntimeError – If credentials are missing or request fails

post_passport(payload: str | Path | Dict[str, Any], dry_run: bool = True) → Dict[str, Any]

Push a passport JSON payload to OceanOPS.

Headers are generated only for this request using the secret token.

Parameters:

• payload (Union[str, Path, Dict[str, Any]]) – Either: - A path to a local JSON file containing the passport payload, or - A Python dictionary representing the payload.

• dry_run (bool) – If True, sets options.dryRun to True to prevent real updates.

Returns:

Response from the API as a Python dictionary.

Return type:

Dict[str, Any]

Raises:

RuntimeError – If credentials are missing or request fails.

validate_passport_json(local_json: str | Path | dict, schema_source: str | Path | None = None) → Tuple[bool, str | None]

Validate a local OceanOPS passport JSON against a schema.

Parameters:

• local_json – Path to JSON file or dict object to validate.

• schema_source – Path to local schema file or URL. Defaults to online schema if None.

Returns:

Tuple (True, None) if valid, otherwise (False, error message).