Making an API Call
When calling the API, your payload must be a JSON object with the following structure:
-
points: an array of objects. Each object should include:
- latitude: a number representing the latitude coordinate (between -90 and 90).
- longitude: a number representing the longitude coordinate (between -180 and 180).
-
timestamp: an ISO 8601 formatted timestamp string (e.g., "2024-05-23T00:00:00Z").
Timestamp Format Details
The timestamp must be in ISO 8601 format with UTC timezone (Z suffix). Examples: - "2024-05-23T00:00:00Z" (midnight UTC) - "2024-05-23T12:30:45Z" (12:30:45 PM UTC)
The API supports timestamps from 3 years in the past up to 10 days in the future. For historical data older than 3 months, the Hindcast-3Y dataset is used. For recent data (5-90 days in the past), the Hindcast-3M dataset is used. For the most recent past and future forecasts, the Forecast dataset is used. See Models for more information about the different datasets and their temporal coverage.
-
variables: an array of strings specifying the requested variables. Valid values are:
- "current": satellite observed ocean currents & tides (intensity, direction)
- "wind": ocean surface winds (intensity, direction)
- "gust": ocean surface wind gust
- "wave": combined wind waves and swell (significant height, mean direction, mean period)
- "bathy": fixed ocean bathymetry
- "sst": sea surface temperature from infrared satellites
- "extra_wave": additional wave parameters including:
- Swell wave data (significant height, mean direction, mean period)
- Wind wave data (significant height, mean direction, mean period)
-
Optional parameters:
- wind_height: float between 10 and 100 (default: 10) to retrieve winds between 10m and 100m
- task_name: a string to help identify your task (useful for tracking multiple requests)
- receive_mail: boolean (default: false) - set to true to receive email notifications
See Models for more information about the different datasets and variables. See Request Processing Modes for details on synchronous vs. asynchronous processing.
API Endpoints
- POST
/MetOcean: Submit a data request - POST
/MetOcean/async: Submit a data request in asynchronous mode - GET
/task/{task_id}: Check the status of a specific task - GET
/user/tasks/PENDING: View all your pending tasks
Authentication
All API calls require an API key, which should be included in the x-api-key header.
Simple Example: Two Points
Here's a basic example showing how to request metocean data for two specific locations and times using the default synchronous mode:
1. Setup and Imports
Required Python libraries for making HTTP requests and handling JSON data.
import requests
import json
2. API Configuration and Authentication
Setting up the API endpoint and authentication credentials.
# API configuration
base_url = 'https://api.amphitrite.fr'
api_key = 'YOUR_API_KEY_HERE'
headers = {
"Content-Type": "application/json",
"x-api-key": api_key # Authentication is handled via API key in headers
}
3. Constructing the Payload
Defining the data points and variables to request from the API.
# Create a simple payload with just two points
payload = {
"points": [
{
"latitude": 47.2, # Atlantic Ocean
"longitude": -32.0,
"timestamp": "2025-01-15T12:00:00Z"
},
{
"latitude": -6.8, # Indian Ocean
"longitude": 79.0,
"timestamp": "2025-01-15T12:00:00Z"
}
],
"variables": ["current", "wind", "wave"], # Request only these variables
"task_name": "example-request" # Optional: helps identify your task
}
4. Making the API Request (Synchronous Mode)
Sending the request to the API and receiving the results directly.
# Make the API request - using synchronous mode (default)
response = requests.post(
f"{base_url}/MetOcean",
headers=headers,
json=payload
)
# Check if the request was successful
if response.status_code == 200:
# Process the results
result = response.json()
print("Request successful!")
print(json.dumps(result, indent=2))
else:
print(f"Request failed with status code: {response.status_code}")
print(response.text)
5. Complete Example
Full code implementation combining all the steps above.
import requests
import json
# API configuration
base_url = 'https://api.amphitrite.fr'
api_key = 'YOUR_API_KEY_HERE'
headers = {
"Content-Type": "application/json",
"x-api-key": api_key
}
# Create a simple payload with just two points
payload = {
"points": [
{
"latitude": 47.2, # Atlantic Ocean
"longitude": -32.0,
"timestamp": "2025-01-15T12:00:00Z"
},
{
"latitude": -6.8, # Indian Ocean
"longitude": 79.0,
"timestamp": "2025-01-15T12:00:00Z"
}
],
"variables": ["current", "wind", "wave"], # Request only these variables
"task_name": "example-request" # Optional: helps identify your task
}
# Make the API request - synchronous mode (default)
response = requests.post(
f"{base_url}/MetOcean",
headers=headers,
json=payload
)
# Check if the request was successful
if response.status_code == 200:
# Process the results
result = response.json()
print("Request successful!")
print(json.dumps(result, indent=2))
else:
print(f"Request failed with status code: {response.status_code}")
print(response.text)
This example demonstrates the key components of an API request: - Authentication: Using an API key in the request headers - Payload Structure: Two specific points with coordinates and timestamps - Variables Selection: Requesting only specific data variables - Synchronous Processing: Getting results directly in the response
For asynchronous processing options, see Request Processing Modes.
Response Format
The API response will have the following structure:
{
"task_id": "unique-task-identifier",
"status": "SUCCESS",
"result": {
"result": [
{
"coordinates": {
"latitude": 47.2,
"longitude": -32.0,
"timestamp": "2025-01-15T12:00:00Z"
},
"conditions": {
"Winds_10m_Direction": 192,
"Winds_10m_Intensity": 14.62,
"Waves_Mean_Direction": 220,
"Waves_Significant_Height": 4.8,
"Waves_Mean_Period": 9.63,
"Currents_Direction": 194,
"Currents_Intensity": 0.21
}
},
// Additional points...
]
"execution_time": 1.23
}
Variable Naming Convention
The response uses the following naming convention for variables:
| Variable Type | Response Field Names |
|---|---|
| Wind | Winds_10m_Direction (degrees), Winds_10m_Intensity (m/s) |
| Wave | Waves_Mean_Direction (degrees), Waves_Significant_Height (m), Waves_Mean_Period (s) |
| Current | Currents_Direction (degrees), Currents_Intensity (m/s) |
| Bathymetry | Bathymetry (m) |
| Sea Surface Temperature | Sea_Surface_Temperature (°C) |
| Extra Wave | Swell_Mean_Direction, Swell_Significant_Height, Swell_Mean_Period, Windwaves_Mean_Direction, Windwaves_Significant_Height, Windwaves_Mean_Period |
| Gust | Gust_10m (m/s) |
Direction Conventions
- Wind and wave directions indicate where the wind/waves are coming FROM
- Current directions indicate where the current is going TO
For failed requests, the response will include an error message:
{
"task_id": "unique-task-identifier",
"status": "FAILURE",
"error": "Error message describing what went wrong"
}
Example: Transatlantic Crossing
Below is a more comprehensive Python script that demonstrates using the API for a transatlantic crossing scenario:
import requests
import json
import pandas as pd
from datetime import datetime, timedelta
def generate_payload(n_points=336):
"""
Generate a payload for a transatlantic crossing (France to US).
10 knots = 10 nautical miles per hour ≈ 0.167 degrees per hour.
Args:
n_points: Number of points to generate
Returns:
dict: Payload for API request
"""
return {
"points": [
{
"latitude": 47.5 + (i * -0.02), # Progressive latitude generation
"longitude": -2.5 + (i * -0.167), # Progressive longitude generation
"timestamp": (datetime(2025, 1, 15) + timedelta(hours=i)).strftime("%Y-%m-%dT%H:%M:%SZ")
}
for i in range(n_points)
],
"variables": ["wind", "wave", "current", "bathy", "sst"],
"task_name": "transatlantic-route-2025" # Adding a descriptive task name
}
def fetch_data(payload, api_key):
"""
Fetch data from the MetOcean API using the default synchronous mode.
Args:
payload: Request payload
api_key: API key for authentication
Returns:
dict: API response
"""
# API endpoint for MetOcean Data
base_url = 'https://api.amphitrite.fr'
url = f'{base_url}/MetOcean'
# Define the headers including API key
headers = {
"Content-Type": "application/json",
"x-api-key": api_key
}
# Send the POST request to the API (synchronous mode)
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
# For synchronous requests, results are directly in the response
return response.json()
else:
print(f"Request failed: {response.status_code}")
print(response.text)
return None
# Example usage
api_key = "YOUR_API_KEY_HERE"
payload = generate_payload(n_points=336) # ~14 days of hourly data
response_data = fetch_data(payload, api_key)
# Process the results
if response_data and response_data.get("status") == "SUCCESS":
results = response_data.get("result", {}).get("results", []) # ← correction
df = pd.DataFrame([
{"timestamp": item["coordinates"]["timestamp"], **item["conditions"]}
for item in results
])
print(f"Retrieved {len(df)} data points")
output_file = "metocean_data.csv"
df.to_csv(output_file, index=False)
print(f"Data saved to {output_file}")
else:
print("Request failed or returned no data")
For information on handling larger requests or using asynchronous mode, see Request Processing Modes.