API Documentation

myshiptracking.com
Get your Free API Key

Our platform delivers real-time terrestrial AIS data designed to power your maritime applications. Engineered for speed, reliability, and consistency, our API gives you access to vessel positions, port details, historical tracks, and comprehensive fleet management functionalities—all wrapped in a standardized response envelope.

Whether you’re developing a maritime tracking system, integrating live data into your dashboard, or creating custom fleet solutions, our API is tailored to support your projects. Be sure to dive into our documentation to explore each endpoint in detail and discover how our platform can meet your operational needs.

API Overview

The MyShipTracking API is a complete solution for integrating live maritime data into your applications. Here’s what our API delivers:

  • Real-Time Vessel Tracking: Get the current position, speed, course, and voyage information for individual vessels.
  • Historical Data & Port Calls: Retrieve comprehensive historical vessel tracks and detailed port call records. Due to terrestrial AIS limitations, historical data is restricted to nearshore areas, and vessel routes may be incomplete.
  • Port Details & Estimates: Access up-to-date port information, search by UN/LOCODE or name, and get arrival estimates.
  • Fleet Management: Create, edit, and manage fleets as well as associate vessels with your fleets.
  • Account Information: Manage your API usage and view your account details.

Every API response is delivered in a consistent JSON or XML envelope to simplify integration.

Important Notice

Please note that the AIS data provided through our service is terrestrial and comes with limited coverage. We recommend that you take advantage of our trial period to verify that the API meets your specific needs before making a purchase. Additionally, due to the nature of terrestrial coverage, there may be instances where vessels remain out of range for extended periods.

Endpoints

Endpoint Description
Vessel Status Retrieve the latest position and voyage details for a specific vessel (supports simple and extended responses).
Vessels Status (Bulk) Fetch information for multiple vessels in a single request.
Vessels In Zone Retrieve a list of vessels within a specified geographic zone.
Vessels Nearby Retrieve a list of vessels that are located within a specified radius (in nautical miles) from a reference vessel’s position.
Vessel History Track Access historical tracking data for a vessel over a defined time period with flexible grouping options.
Vessel Search Search for vessels by name.
Port Details Get detailed information about a port including its UN/LOCODE, country, and timezone.
Port Search Search ports by name or UN/LOCODE.
Vessels In Port Retrieve the list of vessels currently in port along with arrival details.
Port Estimate Obtain estimated arrival times for vessels at a given port based on dynamic parameters.
Port Calls Retrieve historical port call records and events for vessels and ports.
My Fleets List all your fleets along with basic details.
Create Fleet Create a new fleet to organize and manage your vessels.
Edit Fleet Update the details of an existing fleet.
Delete Fleet Remove a fleet from your account (note: you cannot delete your only fleet).
Add Vessel in Fleet Add a vessel to a specific fleet for easier management.
Delete Vessel from Fleet Remove a vessel from your fleet.
List Vessels in Fleet Display all vessels associated with a fleet.
Fleet Status Get live positional data for vessels in your fleets.
Account Info Retrieve your account details and API usage information.
Important: Before using the endpoints, please make sure to read our Terms of Use.

How to Get and Manage Your API Key

To start using our API, register for a free account at MyShipTracking.com.

After registration, navigate to your account page where you can generate your unique API Key and Secret Key. Each user is allowed only one Trial API key which is limited to 2000 coins and a maximum active period of 10 days.

If needed, you have the option to regenerate your API and Secret keys directly from your account page.

Rate Limits, Credits & Overuse Protection

To ensure fair usage and optimal performance, our API employs a robust rate limiting and credit-based system:

  • Valid API Key: Up to 2000 calls per minute
  • Trial Users: Limited to 90 calls per minute
  • Maximum Charge per Request: No matter the calculated cost of an endpoint, you will never be charged more than 500 credits for a single request. If the actual cost exceeds this limit, only 500 credits will be deducted.
  • Overuse Protection: Our system guarantees that you are never charged more than your available coin balance.

Each API call deducts credits based on the endpoint used. Detailed credit costs are provided in the individual endpoint documentation.

Possible Error Responses

The following error responses can be returned. Each error follows the standardized response envelope.

Error Code HTTP Status Description
MST_ERR_VALIDATOR 400 Parameter validation failed (e.g. incorrect format or missing required parameters).
ERR_INVALID_ROUTE 401 Invalid API route. The URL must start with '/api/v' followed by a version number.
ERR_INVALID_IDENTIFIER 400 Either none or more than one identifier was provided; exactly one identifier (e.g. mmsi or port_id/unloco) is required.
ERR_NO_KEY 401 No API key was provided in the request headers.
ERR_INVALID_KEY 401 The provided API key is invalid or unrecognized.
ERR_NOACCESS 403 The API key does not have permission to access this endpoint.
ERR_NO_CREDITS 402 Insufficient credit balance for the requested operation.
ERR_PORT_NOT_FOUND 404 No port or port calls were found matching the provided identifier.
ERR_RATE_LIMIT 429 The request rate limit has been exceeded. Please try again later.
ERR_INTERNAL 500 An internal server error occurred.
ERR_INVALID_SECRET 400 The provided secret is invalid.
ERR_INVALID_TIME_RANGE 400 Invalid time range provided. Either provide both fromdate and todate or provide days (but not both).
ERR_INVALID_DATE 400 Invalid date format for fromdate or todate.
ERR_DATE_RANGE 404 The date range is invalid (e.g. fromdate is after todate or exceeds the maximum allowed range).
ERR_TRIAL_LIMIT 400 Trial users are restricted to a limited time span for data retrieval.
ERR_FLEET_NAME_EXISTS 400 A fleet with that name already exists.
ERR_FLEET_LIMIT_REACHED 400 Fleet limit reached for your account.
ERR_ONE_FLEET 400 Cannot delete the only fleet in your account.
ERR_INVALID_FLEET 400 Fleet not found or not owned by the user.
ERR_VESSEL_ALREADY_EXISTS 400 The vessel already exists in the fleet.
ERR_VESSEL_NOT_FOUND 404 The vessel was not found or is not associated with the specified fleet.

Coverage & Live Map

Our API is exclusively focused on terrestrial AIS data. To view live vessel movements and explore our coverage area, visit MyShipTracking.com and explore the interactive live map.

To begin, use the navigation menu on the left to browse the detailed documentation for each endpoint. Every page includes comprehensive parameter lists, response examples, and code snippets in various programming languages.

Please review the rate limits, credit consumption, and overuse protection details carefully to avoid temporary bans.