API Changes & Migration Guide

Important API Updates

Last updated: January 3, 2026

We've made important improvements to our API. Review the changes below and update your integration accordingly.

View Full API Reference

What's Changed?

Authentication via Headers

API keys must now be passed using the x-api-key header instead of query parameters.

New Endpoint: Vessels by Area

Find all vessels within a geographic radius (max 50km). Costs 10 credits per request.

Rate Limiting

Endpoint-specific rate limits: 15/min default, 50/min for several endpoints, 100/min for vessel-location.

1. Authentication via Headers

For improved security, API keys must now be included in request headers rather than query parameters.

New Method (Required)

import requests

url = "https://datadocked.com/api/vessels_operations/get-vessel-info?imo_or_mmsi=9870666"

headers = {
    "accept": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)

Old Method (Deprecated)

url = "https://datadocked.com/api/vessels_operations/get-vessel-info?api_key=YOUR_API_KEY&imo_or_mmsi=9870666"
response = requests.get(url)

Action Required: Update all API calls to pass your API key in the x-api-key header.

2. New Endpoint: Vessels by Area

NEW

Find all vessels within a specified geographic radius. Perfect for monitoring vessel traffic in ports, coastal areas, or any region of interest.

Endpoint

GET /api/vessels_operations/get-vessels-by-area

Cost

10 credits

Parameters:

latituderequired

Center latitude of the search area (number)

longituderequired

Center longitude of the search area (number)

circle_radiusrequired

Search radius in kilometers (integer, max 50km)

Example Request:

curl -X 'GET' \
  'https://datadocked.com/api/vessels_operations/get-vessels-by-area?latitude=45&longitude=-9&circle_radius=50' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Example Response:

[
  {
    "mmsi": "245297000",
    "name": "ELBEBORG",
    "latitude": "45.078705",
    "longitude": "-8.9553804",
    "speed": "110",
    "course": "185",
    "heading": "184"
  }
]

Try it out: Test this endpoint in our API Playground or view the detailed documentation.

3. Rate Limiting

To ensure fair usage and maintain service quality, we've implemented endpoint-specific rate limits.

Rate Limits by Endpoint:

vessel-location100 requests/min

my-credits, vessel-particulars, vessel-engine, vessel-management, vessels-by-name, vessels-by-area50 requests/min

All other endpoints15 requests/min

If you exceed the limit, you'll receive a 429 Too Many Requests response.

Example 429 Response:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit. Please wait before making more requests."
}

Best Practices:

Track your requests to stay within the limit
Implement exponential backoff when receiving 429 responses
Cache responses when possible
Space out requests if making multiple calls

Need Help?

Check out our complete API documentation for detailed examples, endpoint specifications, and integration guides.

View API Documentation Contact Support