AIS API Documentation

Authentication

All API requests require authentication via an API key. Include your key in theAuthorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705391400

POST/search

Search for vessels by ship name (fuzzy), MMSI, or IMO number. Returns matching vessels with current position data.

Request Body

Example: Search by Ship Name

curl -X POST "https://dev.phoenixai.app/api/ais/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "simply eight",
    "type": "name",
    "limit": 5
  }'

Response

{
  "success": true,
  "count": 1,
  "vessels": [
    {
      "mmsi": "247372200",
      "imo": "1012289",
      "name": "SIMPLY EIGHT",
      "flag": "IT",
      "type": "Yacht",
      "length": 24,
      "position": {
        "lat": 43.6847,
        "lon": 7.2856,
        "timestamp": "2026-01-16T08:30:00Z",
        "speed": 0.0,
        "course": 180,
        "heading": 175
      },
      "destination": "MONACO",
      "eta": "2026-01-17T14:00:00Z"
    }
  ]
}

Example: Search by MMSI

curl -X POST "https://dev.phoenixai.app/api/ais/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "247372200", "type": "mmsi"}'

POST/track

Get historical track points for a vessel. Returns position history with territorial water classification for each point.

Request Body

Example

curl -X POST "https://dev.phoenixai.app/api/ais/track" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mmsi": "247372200",
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-01-07T23:59:59Z",
    "simplify": true
  }'

Response

{
  "success": true,
  "mmsi": "247372200",
  "name": "SIMPLY EIGHT",
  "pointCount": 1247,
  "track": [
    {
      "lat": 43.7384,
      "lon": 7.4246,
      "timestamp": "2026-01-01T00:00:00Z",
      "speed": 8.5,
      "territorial": {
        "zone": "FR_TW",
        "country": "France",
        "type": "territorial_waters"
      }
    },
    {
      "lat": 43.6847,
      "lon": 7.2856,
      "timestamp": "2026-01-01T01:00:00Z",
      "speed": 0.0,
      "territorial": {
        "zone": "MC",
        "country": "Monaco",
        "type": "territorial_waters"
      }
    }
    // ... more points
  ],
  "summary": {
    "totalNauticalMiles": 142.5,
    "territoriesVisited": ["FR", "MC", "IT"],
    "timeInTerritorialWaters": 0.72,
    "timeInHighSeas": 0.28
  }
}

GET/vessel

Get current position and details for a specific vessel by MMSI.

Query Parameters

Example

curl -X GET "https://dev.phoenixai.app/api/ais/vessel?mmsi=247372200" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "vessel": {
    "mmsi": "247372200",
    "imo": "1012289",
    "name": "SIMPLY EIGHT",
    "callsign": "IBHY",
    "flag": "IT",
    "type": "Yacht",
    "length": 24,
    "beam": 6,
    "draft": 2.1,
    "grossTonnage": 85,
    "yearBuilt": 2019,
    "position": {
      "lat": 43.6847,
      "lon": 7.2856,
      "timestamp": "2026-01-16T08:30:00Z",
      "speed": 0.0,
      "course": 180,
      "heading": 175,
      "navStatus": "At anchor"
    },
    "destination": "MONACO",
    "eta": "2026-01-17T14:00:00Z",
    "lastPort": "NICE",
    "territorial": {
      "zone": "MC",
      "country": "Monaco",
      "type": "territorial_waters"
    }
  }
}

Error Codes

All errors return a JSON object with success: false and an error message.

Error Response Example

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retryAfter": 45
  }
}