SeaWay24 API Docs

Leverage vessel intelligence with a powerful, intuitive RESTful API.

API Overview

The SeaWay24 API delivers real-time positions and rich profiles for vessels across the globe. Responses are returned in JSON, enabling quick integration of maritime tracking into your applications.

Real-time data

Updated every 60 seconds.

Global coverage

Over 45,000 vessels worldwide.

High performance

Average response 50 ms.

Secure authentication

API key-based protection.

Base URL

https://api.seaway24.com/v1

Authentication

All API requests require a valid API key supplied via headers or query parameters.

Header authentication (recommended)

GET /api/ships HTTP/1.1
Host: api.seaway24.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Query parameter authentication

GET /api/ships?api_key=YOUR_API_KEY HTTP/1.1
Host: api.seaway24.com

Note: Retrieve your API key in the dashboard and rotate it regularly for security.

Rate Limits

Usage quotas depend on your plan. Exceeding the limit returns HTTP 429.

Plan Monthly requests Requests per second Concurrent connections
Basic 10,000 10 5
Professional 50,000 50 20
Enterprise Unlimited Unlimited 100

Rate limit headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Core Endpoints

GET
/api/ships
List vessels
GET
/api/ships/{id}
Retrieve vessel details
GET
/api/ships/{id}/history
Fetch vessel position history
GET
/api/vessel-types
List vessel types
GET
/api/stats
Service statistics

Ship Data API

List vessels

GET /api/ships

Return live vessel positions.

Query parameters

Parameter Type Description Example
type integer Vessel type filter 70 (cargo)
search string Search by vessel name OCEAN
limit integer Number of results (default: 20, max: 100) 50
offset integer Pagination offset 0
bbox string Bounding box (lat1,lon1,lat2,lon2) 35,126,37,128

Response example

{
  "data": [
    {
      "id": 123,
      "mmsi": 123456789,
      "vessel_name": "OCEAN EXPLORER",
      "vessel_type": 70,
      "latitude": 37.5665,
      "longitude": 126.9780,
      "speed": 12.5,
      "course": 45.0,
      "heading": 44,
      "destination": "BUSAN PORT",
      "timestamp": "2024-01-15T10:30:00Z",
      "status": "active"
    }
  ],
  "pagination": {
    "total": 1250,
    "page": 1,
    "per_page": 20,
    "total_pages": 63
  }
}

Vessel details

GET /api/ships/{id}

Retrieve detailed information for a specific vessel.

Response example

{
  "id": 123,
  "mmsi": 123456789,
  "imo": "IMO1234567",
  "vessel_name": "OCEAN EXPLORER",
  "callsign": "HLCS",
  "vessel_type": 70,
  "vessel_type_name": "Cargo",
  "latitude": 37.5665,
  "longitude": 126.9780,
  "speed": 12.5,
  "course": 45.0,
  "heading": 44,
  "rot": 0,
  "nav_status": 0,
  "draught": 8.5,
  "destination": "BUSAN PORT",
  "eta": "01-15 14:00",
  "timestamp": "2024-01-15T10:30:00Z",
  "status": "active",
  "dimensions": {
    "length": 180,
    "width": 28,
    "to_bow": 120,
    "to_stern": 60,
    "to_port": 14,
    "to_starboard": 14
  }
}

Advanced filtering

Available on Professional plans and higher.

Geospatial filtering

GET /api/ships?bbox=35.1,126.8,37.6,129.2

Speed range filtering

GET /api/ships?speed_min=10&speed_max=20

Multiple vessel types

GET /api/ships?types=70,80,60

Error handling

Standard HTTP status codes convey the success or failure of each request.

200

OK

Request processed successfully.

400

Bad Request

Invalid payload or parameters.

401

Unauthorized

API key missing or invalid.

429

Too Many Requests

Rate limit exceeded.

500

Internal Server Error

Unexpected server-side issue.

Error response format

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "details": "The provided API key is not valid or has expired"
  }
}

Code examples

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const baseURL = 'https://api.seaway24.com/v1';

async function getShips() {
  try {
    const response = await axios.get(`${baseURL}/api/ships`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      params: {
        limit: 10,
        type: 70 // cargo
      }
    });
    
    console.log('Vessel data:', response.data);
    return response.data;
  } catch (error) {
    console.error('API error:', error.response?.data || error.message);
  }
}

// Retrieve details for a specific vessel
async function getShipDetails(shipId) {
  try {
    const response = await axios.get(`${baseURL}/api/ships/${shipId}`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    console.log('Vessel details:', response.data);
    return response.data;
  } catch (error) {
    console.error('API error:', error.response?.data || error.message);
  }
}

getShips();

Python

import requests
import json

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.seaway24.com/v1'

def get_ships():
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    params = {
        'limit': 10,
        'type': 70  # cargo
    }
    
    try:
        response = requests.get(f'{BASE_URL}/api/ships', 
                              headers=headers, 
                              params=params)
        response.raise_for_status()
        
        data = response.json()
        print('Vessel data:', json.dumps(data, indent=2, ensure_ascii=False))
        return data
        
    except requests.exceptions.RequestException as e:
        print(f'API error: {e}')
        return None

def get_ship_details(ship_id):
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    
    try:
        response = requests.get(f'{BASE_URL}/api/ships/{ship_id}', 
                              headers=headers)
        response.raise_for_status()
        
        data = response.json()
        print('Vessel details:', json.dumps(data, indent=2, ensure_ascii=False))
        return data
        
    except requests.exceptions.RequestException as e:
        print(f'API error: {e}')
        return None

# Usage example
ships = get_ships()
if ships and ships['data']:
    first_ship = ships['data'][0]
    get_ship_details(first_ship['id'])

PHP

apiKey = $apiKey;
    }
    
    public function getShips($params = []) {
        $url = $this->baseURL . '/api/ships';
        
        $headers = [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ];
        
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 200) {
            return json_decode($response, true);
        } else {
            throw new Exception("API error: HTTP $httpCode - $response");
        }
    }
    
    public function getShipDetails($shipId) {
        $url = $this->baseURL . "/api/ships/$shipId";
        
        $headers = [
            'Authorization: Bearer ' . $this->apiKey
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 200) {
            return json_decode($response, true);
        } else {
            throw new Exception("API error: HTTP $httpCode - $response");
        }
    }
}

// Usage example
try {
    $api = new SeaWayAPI('YOUR_API_KEY');
    
    $ships = $api->getShips([
        'limit' => 10,
        'type' => 70 // cargo
    ]);
    
    echo "Vessel data:\n";
    echo json_encode($ships, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
    
    if (!empty($ships['data'])) {
        $firstShip = $ships['data'][0];
        $details = $api->getShipDetails($firstShip['id']);
        
        echo "\nVessel details:\n";
        echo json_encode($details, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
    }
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

?>

cURL

# List vessels
curl -X GET "https://api.seaway24.com/v1/api/ships?limit=10&type=70" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Retrieve a specific vessel
curl -X GET "https://api.seaway24.com/v1/api/ships/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Vessel position history
curl -X GET "https://api.seaway24.com/v1/api/ships/123/history?hours=24" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Vessels inside a bounding box
curl -X GET "https://api.seaway24.com/v1/api/ships?bbox=35.1,126.8,37.6,129.2" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDKs & libraries

Official SDKs are available for popular languages.

JavaScript/Node.js

npm install seaway-sdk

GitHub →

Python

pip install seaway

PyPI →

PHP

composer require seaway/sdk

Packagist →

Java

Available on Maven Central

Maven →

Support & contact

Need help or have questions about the API? We are here for you.

Additional docs

In-depth guides and tutorials.

Docs center →

Live support

Chatbot and technical assistance.

Request support →

GitHub

Open-source examples and issue tracking.

GitHub →

Email support

Technical inquiries and partnerships.

api@seaway24.com