Request Processing Modes

Key Information:

• The API supports both synchronous (default) and asynchronous request processing modes
• Synchronous requests maintain a connection with the server until processing completes
• Asynchronous requests return immediately with a task ID for later result retrieval
• All requests generate a task ID which can be used for status checking
• Optional email notifications can be enabled for task completion
• For route requests (~5000 points) prefer synchronous requests
• For larger requests (~100k points) prefer asynchronous requests

Relevant Endpoints

Endpoint	Method	Description
/MetOcean	POST	Submit synchronous data processing requests
/MetOcean/async	POST	Submit asynchronous data processing requests
/task/{task_id}	GET	Retrieve response of a specific task by its ID
/user/tasks	GET	List all your tasks (requires API key authentication)
/user/tasks/PENDING	GET	List only your pending tasks (requires API key authentication)
/user/tasks/SUCCESS	GET	List only your successful tasks (requires API key authentication)
/cancel_task/{task_id}	POST	Cancel a pending or running task

Overview

The MetOcean API supports two processing modes to handle data requests efficiently:

1. Synchronous Mode (Default): The connection is maintained until processing completes, then results are returned directly in the response.
2. Asynchronous Mode: The API immediately returns a task ID, and the client must poll for results separately.

Both modes generate task IDs that allow for status checking and result retrieval, which is particularly useful if a client connection is interrupted during synchronous processing.

Making Requests

Synchronous Mode (Default)

In synchronous mode, the server maintains the connection while processing your request:

response = requests.post(
    "https://api.amphitrite.fr/MetOcean",
    headers={"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY"},
    json={
        "points": [...],
        "variables": [...],
        "task_name": "ship1-leg1"     // Custom identifier for your request (optional)
    }
)

# The response will contain the complete results
results = response.json()

If a client connection is interrupted during synchronous processing, you can recover your task using the methods described in the "Recovering from Connection Loss" section below.

Asynchronous Mode

For requests that may take longer to process, use asynchronous mode with the /MetOcean/async endpoint:

response = requests.post(
    "https://api.amphitrite.fr/MetOcean/async",
    headers={"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY"},
    json={
        "points": [...],
        "variables": [...],
    }
)

# The response contains only the task ID
task_id = response.json().get("task_id")

Email notifications can be enabled for task completion, using the options described in the "Email Notifications" section below.

Checking Task Status

With either mode, you can check the status of a task using its ID:

status_response = requests.get(
    f"https://metocean.app.amphitrite.fr/task/{task_id}",
    headers={"x-api-key": "YOUR_API_KEY"}
)
status = status_response.json()

The status response will include:

{
  "task_id": "unique-task-identifier",
  "status": "PENDING",  // Can be "PENDING", "SUCCESS", or "FAILURE"
  "result": null,       // Will contain data when status is "SUCCESS"
  "error": null         // Will contain error details when status is "FAILURE"
}

Recovering from Connection Loss

If a client loses connection during a synchronous request, you can recover your task:

1. Query your pending tasks:

response = requests.get(
    "https://metocean.app.amphitrite.fr/user/tasks/PENDING",
    headers={"x-api-key": "YOUR_API_KEY"}
)

1. Identify your task using the task_name you provided, or by timestamp:

{
    "username": "user123",
    "user_id": 3,
    "email": "user@example.com",
    "tasks_count": 2,
    "tasks": [
        {
            "task_id": "180b942e-c4a4-46b3-ae99-143fb748353b",
            "status": "PENDING",
            "API_call_time": "2025-03-12T12:17:19.792961",
            "task_name": "ship1-leg1",
            "nbr_points": 5000,
            "variables": ["wind"],
            "estimated_time": "2 minutes",
            "time_left": "1 minutes 49 seconds"
        },
        ...
    ]
}

1. Once you have the task ID, check its status as described above.

Email Notifications

For information about receiving email notifications when tasks start and complete, see the Email Notifications documentation.

Best Practices

Polling Interval

When checking task status, use an appropriate polling interval based on the size of your request:

# For standard requests (~5000 points)
polling_interval = 30  # seconds

# For large requests (~100k points)
polling_interval = 30*60  # seconds

while True:
    status_response = requests.get(f"{base_url}/task/{task_id}", headers=headers)
    status = status_response.json()

    if status["status"] in ["SUCCESS", "FAILURE"]:
        break

    time.sleep(polling_interval)

Task Naming

Always provide a descriptive task_name for important requests:

response = requests.post(
    "https://api.amphitrite.fr/MetOcean",
    headers={"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY"},
    json={
        "points": [...],
        "variables": [...],
        "task_name": "voyage-planning-route1-2025-03-15"  # Descriptive name
    }
)

This makes it much easier to identify your tasks when querying the task list.

Error Handling

Always check for error status in task responses:

if status["status"] == "FAILURE":
    error_message = status.get("error", "Unknown error")
    print(f"Task failed: {error_message}")
    # Implement appropriate error handling logic