Implementation

API Requests

All API methods are called via HTTPS by using the following URL template:

https://api.vesselfinder.com/<METHOD>?userkey=AABBCCDD&param1=value1&param2=value2....

On Success

On successful request API returns the requested information as JSON or XML. The HTTP status code is 200 (OK) for all successful requests and HTTP response headers contain several custom headers with additional information:

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

On Error

All Methods may return errors if the request contains wrong parameters or if the account is expired, blocked or out of credits. By default HTTP status code is 200 (OK) for all error responses if errormode parameter is not used (see next section)

JSON Example

{  
    "error":"ERROR DESCRIPTION"
}

XML Example

<error>ERROR DESCRIPTION</error>

On error, HTTP response headers contain X-API-ERROR header with a short error description.

409 Error Mode

All requests may be called with errormode parameter:

errormode=409

When this parameter is used, HTTP returns status code 409 for all errors. The page content is in plain text and contains a short description of the error.