Vessel Insights | Veson Help Center

Overview

Retrieve verified specification, commercial, and compliance data for vessels in the global merchant fleet. Query a single vessel by IMO number, or retrieve data across multiple vessels by IMO list or vessel type, to enrich operational workflows with accurate, consolidated vessel information without building or maintaining a separate reference data pipeline.

For the full list of available fields, see VI Tiering and Data Fields.

Download the spec

veson-vessel-insights-openapi.yaml

Authentication

Bearer token authentication. Contact your Veson Account Manager or log a ticket at help.veson.com for access.

Authorization: Bearer <token>

Core-only access. If your account holds a Core feature set entitlement only, with no Enhanced or Premium permission, all API calls return an error. Core data is accessible via the Veson platform only, not via this API.

Key concepts

Concept	Meaning
`Vessel`	The core entity returned by all operations. Identified by IMO number, with whichever specification, commercial, and compliance fields the caller's subscription entitles
`IMO Number`	The globally unique vessel identifier issued by the International Maritime Organisation. All lookup operations accept IMO numbers as input
`Feature Set`	Subscription data entitlement. Enhanced subscribers receive a broad set of operational and structural fields. Premium subscribers additionally receive advanced compliance, environmental, and ownership history fields
`referenceData`	The response envelope that wraps all vessel data fields returned by the API
`Quota`	Monthly allowance of vessel records, set by subscription tier. Each unique vessel returned per calendar day counts as one unit, regardless of how many times that vessel is queried within the same day

When to use

Enriching a chartering workbench with vessel particulars
Loading vessel reference data into IMOS without manual entry
Filtering or scoring a fleet against vessel type, size range, or compliance attributes
Building a compliance or commercial monitoring view across a list of vessels

Quota and tiering

Tier	Feature sets included	Monthly API quota
Core	Vessel Identification	No API, dashboard only
Essential	Vessel Identification + Vessel Specification	No API
Enhanced	Vessel Identification + Vessel Specification + API	150 (or 350)
Premium	Vessel Identification + Vessel Specification + Management, Consumption and Environmental + API	800 (or 1500)

Quota enforcement

Call type	Behaviour
Single vessel lookup (`vvdVessel`)	Quota is not enforced. Calls beyond the monthly allowance continue to return data. Overage is logged and may trigger a conversation about upgrading tier
Multi-vessel operations (`vvdVesselsByImos`, `vvdVesselsByType`)	Quota is enforced. If the remaining balance is smaller than the number of vessels requested, the full result set is still returned for that call, it is not truncated. Subsequent calls return empty results until quota resets at the start of the next calendar month

Quota is client-wide: shared across all users and tokens on the account, not per user or per token. Calls that return no data, for example an unrecognised IMO number, do not consume quota.

HTTP status codes

Code	Meaning	Notes
200	OK	Everything worked as expected
400	Bad Request	Often due to a missing required parameter
401	Unauthorized	No valid API key provided
402	Request Failed	Parameters were valid but the request failed
403	Forbidden	API key does not have permission to perform the request
404	Not Found	The requested resource does not exist
409	Conflict	Request conflicts with another request, for example a repeated idempotent key
424	External Dependency Failed	A failure in a dependency external to Veson
429	Too Many Requests	Too many requests too quickly, use exponential backoff
500, 502, 503, 504	Server Errors	Rare, something went wrong on Veson's end

Notes and known limitations

The referenceData response envelope is the current confirmed structure. It is subject to change until integrations begin; any structural change will be communicated in the Changelog
vvdVesselsByType accepts a vessel type or size range parameter, for example CAPESIZE

Operations

	Operation	Method	Purpose
1	vvdVessel	POST	Look up a single vessel by IMO number. Available from Pilot tier upward. Quota monitored but not enforced
2	vvdVesselsByImos	POST	Look up up to 100 vessels in one call by IMO number array. Available from Professional tier upward. Quota enforced
3	vvdVesselsByType	POST	Query vessels matching a given vessel type or size range. Results ordered by IMO number

Each operation page has its full request, response, and GraphQL form.

Field categories

Every vessel record returned under referenceData is organised into these top-level categories. Full field-by-field detail for each category lives in the linked field reference above rather than here, since the nested schema runs to more than 140 sub-objects across the fleet data model.

Category	Covers
`identification`	IMO, name, call sign, flag, vessel type, size range, port registry
`metrics`	Dimensions (LOA, beam, depth, draft), ship size, deadweight variants, tonnes per centimetre
`tonnage`	Gross, net, lakes tonnage, displacement (summer, winter, tropical, lightweight)
`lifecycle`	Build date, shipyard, dry dock history, inspections (SIRE, CDI, PSC, RightShip, BIRE, CAP), rebuild, repower, status history
`machinery`	Main engines, propellers, fuel type by propulsion, power (generators, battery packs)
`equipment`	Cranes/gears, grabs, pumps, scrubbers, ballast water treatment, crude oil washing, inert gas system, manifold, solar panels, helicopter deck
`cargo`	Carrying capacity by cargo type, tanks, holds, grades/segregations, heating, passengers, chemical/gas and reefer specifics
`environment`	CII, EEDI, EEXI, EIV, NOx, GHG rating including RightShip
`management`	Ownership history (registered owner, operator, technical/commercial manager, beneficial owner, ISM manager, pool), classification society, crew, insurance (H&M, P&I)
`operations`	Discharge rate, towing and tug bollard pull
`safety`	Fire safety, RightShip safety score
`structural`	Hull, deck count and strength, ice class, container capacity, standard ship design
`cii` / `consumptionProfiles`	Carbon Intensity Indicator rating history and modelled consumption profiles (separate top-level vessel fields, outside `referenceData`)

VI Tiering and Data Fields, full field list by entitlement