Requesting 2D Map Data (Beta)

The API also supports requesting 2D gridded data for a specified geographical area and time. This is useful for visualizing metocean conditions over a griddeed map or integrating our MetOcean data for weather routing.

API Endpoint: POST /2DMetOcean

Payload Structure

The payload for a 2D map data request should be a JSON object with the following structure:

  • bounding_boxes: An array containing a single object defining the geographical area.
    • latitude: An array of two numbers [min_latitude, max_latitude].
    • longitude: An array of two numbers [min_longitude, max_longitude]. Longitude must be in the -180/180° convention.
    • timestamp: An ISO 8601 formatted timestamp string (e.g., "2024-05-15T00:00:00Z") or an array of two ISO 8601 formatted timestamp strings defining a time range (e.g., ["2024-05-15T00:00:00Z", "2024-05-15T06:00:00Z"]).
  • variable: A string specifying the requested variable. Available variables:
    • "current": Ocean currents & tides.
    • "wind": Ocean surface winds.
    • "wave": Combined wind waves and swell.
  • async: boolean (default: false). Set to true to use asynchronous mode. Asynchronous mode is recommended for large 2D data requests that may have longer processing times. See Request Processing Modes for more details.
  • Optional parameters:
    • task_name: A string to help identify your task.
    • receive_mail: boolean (default: false) - Set to true to receive email notifications (recommended for asynchronous tasks).

Example: Requesting Wind Data for a Bounding Box

import requests
import json
from datetime import datetime

# API Configuration
base_url = 'https://api.amphitrite.fr' # Or your local endpoint e.g., 'http://localhost:5011'
api_key = 'YOUR_API_KEY_HERE'
headers = {
    "Content-Type": "application/json",
    "x-api-key": api_key
}

# Constructing the payload for 2D Wind data
payload_2d_wind = {
    "bounding_boxes": [
        {
            "latitude": [44, 51],
            "longitude": [-15, -1], # Using -180/180° convention
            "timestamp": datetime(2024, 5, 19, 18, 5).strftime("%Y-%m-%dT%H:%M:%SZ")
        }
    ],
    "variable": "wind",
    # "async": True, # Synchronous by default, async: true can be added for long requests
    "task_name": "2D-Wind-Example"
}

# Make the API request
response_2d_wind = requests.post(
    f"{base_url}/2DMetOcean",
    headers=headers,
    json=payload_2d_wind
)

# Process the response (synchronous mode)
if response_2d_wind.status_code == 200:
    data = response_2d_wind.json()
    if data.get("status") == "SUCCESS":
        print("2D Map Data request successful!")
        print(f"Result: {json.dumps(data.get('result'), indent=2)}")
    else:
        print(f"API returned an error: {data.get('error', 'Unknown error')}")
        print(f"Task Info: {json.dumps(data, indent=2)}")
else:
    print(f"2D Map Data request failed with status code: {response_2d_wind.status_code}")
    print(response_2d_wind.text)

Response Format for 2D Map Data

The API response for a successful synchronous 2D map data request will directly contain the results in the structure shown below. If using asynchronous mode (async: true), you would first poll /task/{task_id}, and upon success, the result field of the task status response will contain this structure:

{
  "task_id": "unique-task-identifier",
  "status": "SUCCESS",
  "result": {
    "results": [ // Note: currently supports a single bounding box, so one item in this list
      {
        "coordinates": {
          "latitude": [44.0, 44.25, ..., 51.0], // Array of latitude values for the grid
          "longitude": [-15.0, -14.75, ..., -1.0], // Array of longitude values for the grid
          "timestamp": "2024-05-19T18:00:00Z" // Timestamp of the returned data grid
          // Or if a time range was requested:
          // "timestamp": ["2024-05-15T00:00:00Z", "2024-05-15T01:00:00Z", ...]
        },
        "conditions": {
          // Variable specific fields, e.g., for "wind":
          "Winds_10m_Direction": [
            [270, 271, ..., 275], // Grid of direction values
            ...
            [280, 281, ..., 285]
          ],
          "Winds_10m_Intensity": [
            [10.1, 10.2, ..., 10.5], // Grid of intensity values
            ...
            [11.1, 11.2, ..., 11.5]
          ]
          // For "wave": "Waves_Mean_Direction", "Waves_Significant_Height", "Waves_Mean_Period"
          // For "current": "Currents_Speed", "Currents_Direction"
        }
      }
    ]
  }
}

The latitude and longitude arrays in coordinates define the grid axes. The corresponding data in conditions (e.g., Winds_10m_Intensity) will be a 2D array (list of lists) where each inner list corresponds to a latitude row.

Important Considerations for 2D Map Data

  • Longitude Convention: Ensure longitude values in the request are in the -180/180° convention (not 0/360°).
  • Available Variables: Currently, "current", "wind", and "wave" are supported for 2D map data.
  • Single Bounding Box: The API currently handles requests with a single bounding box definition, not a list of multiple bounding boxes.
  • Response Time & Time Range:
    • For currents, response time can increase significantly if the requested timestamp range spans multiple days. For optimal performance with currents when response time is critical, consider requesting a time range with two timestamps within the same day (e.g., "timestamp": ["2025-05-15T00:00:00Z", "2025-05-15T06:00:00Z"]).
    • Response time is generally faster for wind and wave data compared to currents.
  • Single Timestamp Interpolation: For requests with a single timestamp, the API response returns data for the exact timestamp requested, not necessarily the nearest available data point used for interpolation by the underlying models.
  • Long Processing Times: Some 2D map requests, particularly for large areas, long time ranges, or the current variable, can take significant time to process. For such cases, using async: true in your payload is recommended. See Request Processing Modes.