All API methods are accessed securely over HTTPS using the following URL structure:
https://api.vesselfinder.com/<METHOD>?userkey=AABBCCDD¶m1=value1¶m2=value2....
Upon a successful request, the API returns the requested data in either JSON or XML format. A standard HTTP status code 200 (OK) is returned for successful responses, along with custom HTTP headers containing additional metadata:
| Header | Description |
|---|---|
| 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 |
| X-API-ADDED-IMO | IMO numbers added to your list |
| X-API-ADDED-MMSI | MMSI numbers added to your list |
| X-API-DELETED-IMO | IMO numbers deleted from your list |
| X-API-DELETED-MMSI | MMSI numbers deleted from your list |
| X-API-REMAINING-SLOTS-OLD | Remaining list changes before your request |
| X-API-REMAINING-SLOTS-NEW | Remaining list changes after your request |
All methods may return errors if the request includes invalid parameters or if the account is expired, blocked, or has insufficient credits. By default, error responses return an HTTP status code of 200 (OK) unless the errormode parameter is specified (see next section for details).
{
"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.
You can optionally include the errormode=409 parameter in any request. When specified, the API will return an HTTP status code 409 (Conflict) for all error responses. The response body will be in plain text, containing a brief description of the error.