Implementation

API Requests

All API methods are accessed securely over HTTPS using the following URL structure:

https://api.vesselfinder.com/<method>?userkey=YOUR_API_KEY&param=value&…

For example:

https://api.vesselfinder.com/vessels?userkey=YOUR_API_KEY&imo=9175717

On Success

On success, the API returns the requested data in JSON or XML format with HTTP status 200 (OK), along with custom HTTP headers containing additional metadata:

Header	Description
All methods
`X-API-EXPIRATION-DATE`	Expiration date of your account
`X-API-BALANCE-OLD`	Credit balance before your request
`X-API-CREDIT-COST`	Credits charged for your request
`X-API-BALANCE-NEW`	Remaining credits after your request
ListManager only
`X-API-ADDED-IMO`	Number of IMO added to your list (already listed are not counted)
`X-API-ADDED-MMSI`	Number of MMSI added to your list (already listed are not counted)
`X-API-DELETED-IMO`	Number of IMO deleted from your list (not listed are not counted)
`X-API-DELETED-MMSI`	Number of MMSI deleted from your list (not listed are not counted)
`X-API-REMAINING-SLOTS-OLD`	Vessels you can still add this month, before your request
`X-API-REMAINING-SLOTS-NEW`	Vessels you can still add this month, after your request

Clients must ignore unknown fields. New fields may be added without notice.

On Error

All methods may return errors if the request includes invalid parameters or if the account is expired, blocked, or has insufficient credits. By default, errors are returned with HTTP status 200 (OK), so always check the response body for an error field. To get HTTP 409 instead, use the errormode parameter (see 409 Error Mode below).

{
    "error":"ERROR DESCRIPTION"
}

<error>ERROR DESCRIPTION</error>

In the event of an error, the HTTP response includes an X-API-ERROR header containing a brief description of the issue.

Common error messages (not a complete list):

Message	Cause
`Invalid Userkey!`	Wrong or unknown API key
`[IMO\|MMSI] parameter is required`	No vessel given (VesselsList: your list is empty)
`Invalid IMO "12345"`	Malformed IMO number
`Time interval is mandatory!`	PortCalls without `interval`, dates or `last_id`
`locode is mandatory for [ExpectedArrivals] method`	ExpectedArrivals without `locode`
`Mandatory parameter "from"`	Distance without `from`
`path not found`	Distance: no route (e.g. `ECA=deny`)
`Too frequent requests!`	VesselsList / LiveData called too often

409 Error Mode

Add errormode=409 to any request to get errors as HTTP 409 (Conflict) with a plain-text body containing a brief description of the error. This is useful with HTTP clients that treat non-2xx responses as errors.