VesselAPI Documentation

Welcome to VesselAPI. This API provides access to real-time and short-term historical AIS vessel tracking, port events, NAVTEX safety messages, global port data, and navigation infrastructure.

Quick Start

1. Sign up for an API key at vesselapi.com
2. Include your API key in the Authorization header
3. Make requests to the endpoints
4. Process the JSON responses

API Categories

Documentation is organized by API category:

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of every request.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.vesselapi.com/v1/vessel/123456789?filter.idType=mmsi" \
     -H "Authorization: Bearer YOUR_API_KEY"

Usage Quotas

Each subscription tier has a monthly request quota. When your key exceeds its monthly quota, the API returns HTTP 429. Track remaining usage via the X-RateLimit-Remaining response header.

Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

Error Types

Error Codes

Error Response Format

All errors return a JSON object with an error key. The fields included vary by error type.

400 Bad Request

Includes param and doc_url fields to help identify the issue.

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid MMSI: abc123",
    "code": "invalid_mmsi",
    "param": "mmsi",
    "doc_url": "https://vesselapi.com/docs#invalid_mmsi"
  }
}

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "message": "api key is invalid or not found",
    "code": "invalid_api_key"
  }
}

404 Not Found

{
  "error": {
    "type": "not_found_error",
    "message": "Vessel with MMSI 999999999 not found.",
    "code": "resource_missing"
  }
}

429 Too Many Requests

{
  "error": {
    "type": "rate_limit_error",
    "message": "API monthly quota exceeded",
    "code": "rate_limit_exceeded"
  }
}

500 Internal Server Error

Includes a unique tracking ID and timestamp for support.

{
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please reference error ID 550e8400-e29b-41d4-a716-446655440000 when contacting support if this issue persists.",
    "code": "internal_error",
    "error_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-10-31T15:30:45Z"
  }
}

Reference the error_id when contacting support for faster resolution.

503 Service Unavailable

{
  "error": {
    "type": "service_unavailable_error",
    "message": "The service is temporarily unavailable. Retry after a brief delay.",
    "code": "service_unavailable"
  }
}

Pagination

List endpoints support pagination using cursor-based navigation.

Parameters

Response Format

{
  "vessels": [...],
  "nextToken": "eyJsYXN0X2lkIjoxMjM0NTY3ODl9"
}

The array key varies by endpoint (e.g., vessels, vesselPositions, ports, portEvents, navtexMessages, emissions, casualties, inspections, dgpsStations, lightAids, radioBeacons, modus). The nextToken field is at the top level of the response.