Status

Description

The Status method returns your remaining credits and the expiration date of your account. The method is free of charge.

URL format

https://api.vesselfinder.com/status?userkey=YOUR_API_KEY&param=value&…

Parameters

Parameter	Required	Type	Default	Description
`userkey`	yes	text	-	Your personal API key
`format`	no	text	json	Response format `json` or `xml`

Response fields

Field	Type	Description
`CREDITS`	integer	Remaining credits
`EXPIRATION_DATE`	datetime	Expiration date of your account (UTC), `YYYY-MM-DD HH:MM:SS`

VesselsList accounts

For accounts with the VesselsList method, the response also includes the state of your vessel list (see ListManager).

Field	Type	Description
`LIST_LIMIT`	integer	Maximum number of vessels in your list (IMO and MMSI together)
`REMAINING_SLOTS`	integer	Vessels you can still add to your list this month. Deleting does not free a slot
`MMSI_LIST`	integer	Number of MMSI in your list
`IMO_LIST`	integer	Number of IMO in your list

Code examples

curl "https://api.vesselfinder.com/status?userkey=YOUR_API_KEY"

import requests

resp = requests.get(
    "https://api.vesselfinder.com/status",
    params={"userkey": "YOUR_API_KEY"},
    timeout=30,
)
data = resp.json()
if "error" in data:
    raise RuntimeError(data["error"])

print(data["CREDITS"], data["EXPIRATION_DATE"])

<?php
$query = http_build_query(['userkey' => 'YOUR_API_KEY']);
$data = json_decode(file_get_contents("https://api.vesselfinder.com/status?$query"), true);
if (isset($data['error'])) {
    throw new Exception($data['error']);
}

echo "{$data['CREDITS']} {$data['EXPIRATION_DATE']}\n";

// Node.js 18+ (save as status.mjs)
const params = new URLSearchParams({ userkey: 'YOUR_API_KEY' });
const resp = await fetch(`https://api.vesselfinder.com/status?${params}`);
const data = await resp.json();
if (data.error) throw new Error(data.error);

console.log(data.CREDITS, data.EXPIRATION_DATE);

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
)

func main() {
	q := url.Values{"userkey": {"YOUR_API_KEY"}}
	resp, err := http.Get("https://api.vesselfinder.com/status?" + q.Encode())
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var status struct {
		CREDITS         int
		EXPIRATION_DATE string
		Error           string
	}
	if err := json.NewDecoder(resp.Body).Decode(&status); err != nil {
		log.Fatal(err)
	}
	if status.Error != "" {
		log.Fatal(status.Error)
	}
	fmt.Println(status.CREDITS, status.EXPIRATION_DATE)
}

Examples

Remaining credits and expiration date

GET https://api.vesselfinder.com/status?userkey=YOUR_API_KEY

{
    "CREDITS": 60134,
    "EXPIRATION_DATE": "2025-11-29 22:00:00"
}

<STATUS>
  <CREDITS>60134</CREDITS>
  <EXPIRATION_DATE>2025-11-29 22:00:00</EXPIRATION_DATE>
</STATUS>

VesselsList account

GET https://api.vesselfinder.com/status?userkey=YOUR_API_KEY

{
    "CREDITS": 60134,
    "LIST_LIMIT": 100,
    "REMAINING_SLOTS": 20000,
    "MMSI_LIST": 0,
    "IMO_LIST": 0,
    "EXPIRATION_DATE": "2025-11-29 22:00:00"
}

<STATUS>
  <CREDITS>60134</CREDITS>
  <LIST_LIMIT>100</LIST_LIMIT>
  <REMAINING_SLOTS>20000</REMAINING_SLOTS>
  <MMSI_LIST>0</MMSI_LIST>
  <IMO_LIST>0</IMO_LIST>
  <EXPIRATION_DATE>2025-11-29 22:00:00</EXPIRATION_DATE>
</STATUS>