You have a vessel’s name (or IMO) and you need an MMSI you can actually track. By the end of this guide you’ll query the Vessels API from Python to search by name/IMO, resolve the MMSI, and feed it into the tracking endpoint—using copy‑pasteable code and production‑ready handling of responses.
What you’ll build and when to use it
This walkthrough covers a focused workflow: turn a vessel name or IMO into a trackable MMSI. You’ll call a single search endpoint to resolve identity, then call the tracking endpoint with the MMSI you chose. This is the right pattern when you have user input or an operational vessel list that stores names/IMOs, but you need MMSIs for downstream tracking and analytics.
- Input: vessel name string (partial or full) or an IMO.
- Output: MMSI(s) you can pass to tracking.
- Follow‑up: request track data for the resolved MMSI.
Endpoints, auth, and docs you’ll use
Base URL: https://vessels-api.com/api/V1
Auth: send your key in the X-API-Key header on every request.
Primary endpoint for this article: GET /vessels/search (query parameter: search) to resolve name/IMO to MMSI.
Next step: GET /vessel/track with the MMSI you selected. Live position is part of Professional+ and runs on a separate quota from search.
Documentation and ecosystem:
Search a vessel by name or IMO (curl)
The search endpoint accepts a single query parameter, search. Provide either a name or an IMO and you’ll get a response envelope with your candidates under data. Include X-API-Key in the request header.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://vessels-api.com/api/V1/vessels/search?name=ATLANTIC"Keep the following in mind:
- The JSON envelope is consistent across endpoints: {status, success, message, data}.
- When success is true, data contains your results. When false, check message for error details and do not assume data is present.
- Name searches may return multiple matches; you’ll choose the right MMSI using the metadata in each object.
Search the same endpoint from Python
Below is a minimal Python example calling the same GET /vessels/search endpoint. It includes basic handling for success=false and a simple way to pick an MMSI from the results. Adapt the selection logic for your matching rules (e.g., exact case-insensitive name match, best score, or IMO precedence).
import os
import sys
import requests
BASE_URL = "https://vessels-api.com/api/V1"
API_KEY = os.getenv("VESSELS_API_KEY", "YOUR_API_KEY") # replace or set env var
def search_vessel(query: str):
url = f"{BASE_URL}/vessels/search"
headers = {"X-API-Key": API_KEY}
params = {"search": query}
r = requests.get(url, headers=headers, params=params, timeout=15)
r.raise_for_status()
payload = r.json()
# Envelope: {status, success, message, data}
success = payload.get("success", False)
if not success:
# message contains human-readable detail when success=false
msg = payload.get("message", "Unknown error")
raise RuntimeError(f"Search failed: {msg}")
results = payload.get("data") or []
if not results:
return None # no match
# Example selection strategy:
# 1) If any item has an exact case-insensitive name match, prefer it.
# 2) Otherwise, just pick the first result.
# You can alter this to prioritize IMO matches, flags, or other metadata.
query_lower = query.lower()
exact = [v for v in results if str(v.get("name", "")).lower() == query_lower]
chosen = (exact[0] if exact else results[0])
# Safely read MMSI/IMO if present. Fields depend on the API response object.
mmsi = chosen.get("mmsi")
imo = chosen.get("imo")
if not mmsi:
# If your workflow requires MMSI, treat missing values explicitly.
# You can attempt a follow-up query using IMO if provided.
raise ValueError(f"No MMSI found in selected result: {chosen}")
return {
"mmsi": mmsi,
"imo": imo,
"raw": chosen, # Keep full object for audit/logging
}
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: python search.py <vessel-name-or-IMO>", file=sys.stderr)
sys.exit(2)
query = sys.argv[1]
try:
result = search_vessel(query)
if result is None:
print("No results for query:", query)
else:
print("Selected MMSI:", result["mmsi"])
if result.get("imo"):
print("IMO:", result["imo"])
# You can now call /vessel/track with result["mmsi"]
except Exception as e:
print("Error:", e, file=sys.stderr)
sys.exit(1)
Resolve the MMSI and track
Once you’ve chosen an MMSI from /vessels/search, call /vessel/track with that MMSI for time‑series position data. The live-position capability is part of Professional+ and consumes a separate quota from search.
The official tracking sample below is for MMSI 258785000 (ZJ ATLANTIC) and is dated 2026-02-09. Use this MMSI after you resolve a name match, or substitute the MMSI you found in your own search results.
import os, urllib.request
req = urllib.request.Request(
"https://vessels-api.com/api/V1/vessels/search?name=ATLANTIC",
headers={"X-API-Key": os.environ["VESSELS_KEY"]},
)
print(urllib.request.urlopen(req).read().decode())What the official JSON shows and how to use it
The response follows the same envelope with keys: status, success, message, data.
- status: HTTP-like status indicator within the body.
- success: boolean gate. Always check this before touching data.
- message: human-readable explanation; useful for logs and user messages on error.
- data: the track payload. Pull the MMSI you requested and the time/position fields from here for your map or analytics.
Practical handling tips:
- Guard against missing values. If a field you expect is absent, don’t crash—fallback, skip, or retry based on your needs.
- Do not assume units or timezones; use values as returned by the API and store the original strings alongside parsed types in your database. If you transform times, standardize consistently in your own system.
- If you cache results, keep name→MMSI mappings fresh by re‑searching on a schedule (name spellings and vessel registrations can change). Cache tracking responses cautiously if you display “live” information.
Plan, trial, and going live
Starter is $19.99/mo for 2,500 calls and includes a 7‑day trial. Live-position queries use Professional+ and their own quota. If you only need to resolve MMSIs from names/IMOs, the Starter plan is a lightweight way to wire up your resolver and test your matching logic.
A production checklist that saves time
- Authentication: set X-API-Key in every request; keep keys in environment variables or a secrets manager.
- Retries: retry idempotent GETs that fail with transient network errors. When success=false, read message and decide whether to retry or surface to the user.
- Matching: name queries can return multiple candidates. Build a ranking strategy (exact match, IMO present, flag or type match). Log your chosen record for traceability.
- Caching: cache name→MMSI resolutions to reduce duplicate searches. Invalidate on user edit or periodic refresh.
- Quotas: separate your search and tracking budgets; they are independent. Track usage per service to avoid surprises.
- Scope: there is no geofence endpoint; keep your logic client‑side or within your own backend if you need geographic filtering.
Go live in four steps
- Register for your 7‑day trial.
- Copy your X-API-Key.
- Call GET /api/V1/vessels/search with a name or IMO (query parameter: search) to resolve one or more MMSIs.
- Pass the selected MMSI to GET /api/V1/vessel/track to retrieve track data.
FAQ
How do I handle multiple results for the same name?
Rank the candidates and choose one deterministically (e.g., exact case-insensitive name match first, then IMO-present results, then first result). Keep the full selected object for audit. If your UI allows, let the user confirm among candidates.
What happens when success=false?
Never read data when success=false. Inspect message for a parsable explanation, log it, and decide whether to retry or inform the user. Some failures are transient (network), others are permanent (invalid query).
Does the API provide a geofence filter?
No. There is no geofence endpoint. If you need geographic constraints, filter the results in your own service after retrieving them.
Which plan do I need for live positions?
Live-position is Professional+ and uses a separate quota from search. You can still build and test search-to-MMSI resolution on Starter.
Where can I explore related endpoints or SDKs?
Start with the Documentation and the MCP hub.
Ready to turn names and IMOs into trackable MMSIs in your app? Start your 7‑day trial, grab your key, and ship your resolver today: Register.