ShipLookup API Documentation

Comprehensive maritime vessel data API for developers. Access detailed ship information including IMO numbers, vessel specifications, and ownership details.

🔑 Authentication

All API requests require authentication using an API key. You can obtain an API key by creating an account and generating one in your dashboard.

Authentication Methods

X-API-Key Header

X-API-Key: YOUR_API_KEY

⚠️ Security Note: Keep your API key secure and never expose it in client-side code. Treat it like a password.

🌐 Base URL

https://shiplookup.com/api

All API endpoints are relative to this base URL. All requests must be made over HTTPS.

⚡ Rate Limits

Per Minute

60 requests

Per Hour

1,000 requests

Rate limit headers are included in all responses to help you track your usage.

🚢 Get All Ships

Endpoint

GET /api/ships

Description

Retrieve a paginated list of ships from the database. This endpoint is useful for browsing available vessels or implementing data export functionality.

Query Parameters

Parameter	Type	Default	Description
limit	integer	10	Number of ships to return (1-100)
offset	integer	0	Number of ships to skip for pagination

Example Request

curl -X GET "https://shiplookup.com/api/ships?limit=5&offset=0" \
-H "Authorization: X-API-Key YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "imo": 9876543,
      "mmsi": 123456789,
      "name": "Ocean Explorer",
      "vesselName": "OCEAN EXPLORER",
      "callsign": "ABCD123",
      "length": 200.5,
      "beam": 32.0,
      "grossTonnage": 45000,
      "yearBuilt": 2015,
      "shipType": "Container Ship",
      "flag": "Panama",
      "aisType": "Container Ship",
      "aisFlag": "Panama"
    }
  ],
  "meta": {
    "userId": "user_123",
    "apiKeyId": "key_456",
    "timestamp": "2025-01-27T10:30:00Z",
    "pagination": {
      "limit": 5,
      "offset": 0,
      "count": 1
    }
  }
}

🔍 Get Ship by IMO

Endpoint

GET /api/ships/{imo}

Description

Retrieve detailed information about a specific ship using its International Maritime Organization (IMO) number. This endpoint provides comprehensive vessel data and consumes 1 credit per request.

Path Parameters

Parameter	Type	Description
imo	integer	The IMO number of the ship (numeric only)

Example Request

curl -X GET "https://shiplookup.com/api/ships/9876543" \
-H "Authorization: X-API-Key YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "imo": 9876543,
    "mmsi": 123456789,
    "name": "Ocean Explorer",
    "vesselName": "OCEAN EXPLORER",
    "callsign": "ABCD123",
    "length": 200.5,
    "beam": 32.0,
    "grossTonnage": 45000,
    "yearBuilt": 2015,
    "shipType": "Container Ship",
    "flag": "Panama",
    "aisType": "Container Ship",
    "aisFlag": "Panama"
  },
  "meta": {
    "timestamp": "2025-01-27T10:30:00Z",
    "creditsUsed": 1,
    "creditsRemaining": 299
  }
}

🔎 Search Ships

Endpoint

GET /api/ships/search

Description

Search for ships using various criteria including IMO, MMSI, name, vessel name, or callsign. At least one search parameter is required. Text searches are case-insensitive and support partial matches.

Query Parameters

Parameter	Type	Required	Description
name	string	No	Partial name search (case-insensitive)
vessel_name	string	No	Partial vessel name search
callsign	string	No	Partial callsign search
limit	integer	No	Number of results to return (1-100, default: 10)

Example Requests

Search by IMO:

curl -X GET "https://shiplookup.com/api/ships/search?imo=9876543" \
-H "Authorization: X-API-Key YOUR_API_KEY"

Search by name:

curl -X GET "https://shiplookup.com/api/ships/search?name=ocean&limit=5" \
-H "Authorization: X-API-Key YOUR_API_KEY"

Search by callsign:

curl -X GET "https://shiplookup.com/api/ships/search?callsign=ABCD" \
-H "Authorization: X-API-Key YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "imo": 9876543,
      "mmsi": 123456789,
      "name": "Ocean Explorer",
      "vesselName": "OCEAN EXPLORER",
      "callsign": "ABCD123",
      "length": 200.5,
      "beam": 32.0,
      "grossTonnage": 45000,
      "yearBuilt": 2015,
      "shipType": "Container Ship",
      "flag": "Panama",
      "aisType": "Container Ship",
      "aisFlag": "Panama"
    }
  ],
  "meta": {
    "userId": "user_123",
    "apiKeyId": "key_456",
    "timestamp": "2025-01-27T10:30:00Z",
    "count": 1,
    "limit": 10,
    "searchParams": {
      "imo": null,
      "mmsi": null,
      "name": "ocean",
      "vessel_name": null,
      "callsign": null
    }
  }
}

✅ Test Authentication

Endpoint

GET /api/test-auth

Description

Test endpoint to verify your API key is valid and working correctly. This endpoint doesn't consume any credits and is useful for debugging authentication issues.

Example Request

curl -X GET "https://shiplookup.com/api/test-auth" \
-H "Authorization: X-API-Key YOUR_API_KEY"

Example Response

{
  "message": "API key is valid!",
  "userId": "user_123",
  "apiKeyId": "key_456"
}

📊 Data Models

Ship Object

Field	Type	Description
imo	integer	International Maritime Organization number
mmsi	integer	Maritime Mobile Service Identity number
name	string	Ship name as registered
vesselName	string	Vessel name in uppercase format
callsign	string	Radio callsign identifier
length	number	Ship length in meters
beam	number	Ship width in meters
grossTonnage	integer	Gross tonnage capacity
yearBuilt	integer	Year the ship was built
shipType	string	Type of ship (e.g., "Container Ship", "Tanker")
flag	string	Country of registration
aisType	string	AIS ship type classification
aisFlag	string	AIS flag state

❌ Error Codes

The API uses standard HTTP status codes to indicate success or failure. All error responses include a descriptive error message.

400 - Bad Request

Invalid parameters or malformed request

{
  "error": "Limit must be between 1 and 100"
}

401 - Unauthorized

Missing or invalid API key

{
  "error": "API key required"
}

402 - Payment Required

Insufficient credits for the request

{
  "error": "Insufficient credits"
}

404 - Not Found

Ship not found with the provided IMO

{
  "error": "Ship with IMO 9876543 not found"
}

429 - Too Many Requests

Rate limit exceeded

{
  "error": "Rate limit exceeded"
}

500 - Internal Server Error

Unexpected server error

{
  "error": "Internal server error"
}

💰 Credits System

The ShipLookup API uses a credit-based system to manage usage and ensure fair access to our maritime database.

Get All Ships

Free

No credits consumed

Search Ships

Free

No credits consumed

Get Ship by IMO

1 Credit

This endpoint consumes 1 credit per request and provides detailed ship information.

💡 Tip: Use the search endpoint to find ships without consuming credits, then use the specific IMO lookup for detailed information when needed.

🚀 Getting Started

Create an Account

Generate API Key

Go to your dashboard and generate an API key

Test Your Setup

Use the test endpoint to verify your API key works

Start Building

Integrate our API into your application

🆘 Support

Need help with the API? We're here to assist you with integration and technical questions.

📧 Email Support

📚 Documentation

This page contains all the information you need