API Explorer
Maritime vessel tracking and marine navigation data API providing real-time AIS data, vessel information, port events, and nautical infrastructure locations. Every response carries an X-Request-ID header; authenticated responses also carry X-RateLimit-Remaining (remaining monthly quota, or "Unlimited"). 429 responses have two causes: monthly quota exhausted, or more than 20 concurrent in-flight requests (Retry-After: 1). Any authenticated endpoint can return 403 when the API key is temporarily suspended for sustained quota abuse (the Retry-After header gives the wait). Unknown query parameters are rejected with 400.
Base URL: https://api.vesselapi.com
API Authentication
Enter your API key once to test all endpoints using the "Try It" feature below.
Your API key is stored only in memory and never logged or transmitted except for API requests.
Vessels
more in v1Retrieve vessel information including positions, static data, and estimated time of arrival by MMSI, IMO, name, or location
/v1/location/vessels/bounding-box
v1
🔒 Auth Required
Get vessels within a bounding box
Retrieves vessels within a specified bounding box and time window. Max bbox span: |dLat| + |dLon| ≤ 4 degrees. Max time window (time.to - time.from): 4 hours; for longer ranges issue sequential 4h calls and stitch results client-side using half-open intervals (one slice's time.to = T, next slice's time.from = T + 1ms) to avoid boundary duplicates. A `nextToken` is only valid when reused with the same `time.from`/`time.to`; the API does not reject mismatched bounds and silently returns rows from the wrong slice.
| Name | Type | In | Description |
|---|---|---|---|
filter.lonLeft
*
|
number | query |
Longitude of the left (western) edge of the bounding box
Example:
4.8 |
filter.lonRight
*
|
number | query |
Longitude of the right (eastern) edge of the bounding box
Example:
5 |
filter.latBottom
*
|
number | query |
Latitude of the bottom (southern) edge of the bounding box
Example:
51.5 |
filter.latTop
*
|
number | query |
Latitude of the top (northern) edge of the bounding box
Example:
52 |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago). Max window 4 hours. |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time). Max window 4 hours. |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
VesselsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"vessels": [
{
"cog": 231.5,
"heading": 230,
"imo": 9321483,
"latitude": 1.2644,
"location": {},
"longitude": 103.8215,
"mmsi": 477045900,
"nav_status": 0,
"processed_timestamp": "string",
"sog": 14.1,
"suspected_glitch": false,
"timestamp": "string",
"vessel_name": "EVER GIVEN"
}
]
}
/v1/location/vessels/radius
v1
🔒 Auth Required
Get vessels within a radius
Retrieves vessels within a specified radius of a given point and a given time range. Max radius: 100 km. Max time window (time.to - time.from): 4 hours; for longer ranges issue sequential 4h calls and stitch results client-side using half-open intervals (one slice's time.to = T, next slice's time.from = T + 1ms) to avoid boundary duplicates. A `nextToken` is only valid when reused with the same `time.from`/`time.to`; the API does not reject mismatched bounds and silently returns rows from the wrong slice.
| Name | Type | In | Description |
|---|---|---|---|
filter.longitude
*
|
number | query |
Longitude of the center point
Example:
4.5 |
filter.latitude
*
|
number | query |
Latitude of the center point
Example:
51.5 |
filter.radius
*
|
number | query |
Search radius in meters (max 100,000 = 100 km)
Example:
10000 |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago). Max window 4 hours. |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time). Max window 4 hours. |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
VesselsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"vessels": [
{
"cog": 231.5,
"heading": 230,
"imo": 9321483,
"latitude": 1.2644,
"location": {},
"longitude": 103.8215,
"mmsi": 477045900,
"nav_status": 0,
"processed_timestamp": "string",
"sog": 14.1,
"suspected_glitch": false,
"timestamp": "string",
"vessel_name": "EVER GIVEN"
}
]
}
/v1/search/vessels
v1
🔒 Auth Required
Search for Vessels
Retrieves a list of vessels matching the given filters. At least one filter parameter (or the unified `q` parameter) is required.
| Name | Type | In | Description |
|---|---|---|---|
q
|
string | query |
Unified search across IMO, MMSI, callsign, and vessel name. Matches a vessel if any of those identifiers matches. Name and callsign also accept SQL LIKE wildcards (% and _). Can be combined with filter.* parameters.
Example:
EVER GIVEN |
filter.name
|
string | query |
Name of the vessel
Example:
EVER GIVEN |
filter.callsign
|
string | query |
Radio callsign of the vessel
Example:
H3RC |
filter.flag
|
array | query |
ISO 2-letter country code(s) of the flag state. Repeat the parameter to match multiple.
Example:
PA |
filter.vesselType
|
array | query |
Vessel type classification(s) (case-insensitive). Repeat the parameter to match multiple.
Example:
Container Ship |
filter.mmsi
|
integer | query |
MMSI number
Example:
477045900 |
filter.imo
|
integer | query |
IMO number
Example:
9321483 |
filter.yearBuiltMin
|
integer | query |
Minimum year built
Example:
2010 |
filter.yearBuiltMax
|
integer | query |
Maximum year built
Example:
2020 |
filter.classSociety
|
array | query |
Classification society/societies (case-insensitive). Repeat the parameter to match multiple.
Example:
Lloyd's Register |
filter.owner
|
string | query |
Owner name (partial match, case-insensitive)
Example:
Evergreen |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
FindVesselsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"vessels": [
{
"breadth": 59,
"breadth_unit": "m",
"builder": "Imabari Shipbuilding",
"call_sign": "H3RC",
"class_society": "American Bureau of Shipping",
"country": "Panama",
"country_code": "PA",
"deadweight_tonnage": 199629,
"draft": 16,
"draft_unit": "m",
"draught_calculated_avg": 13.8,
"draught_observed_max": 16,
"engine_model_name": "string",
"engine_type": 0,
"eni": "02320524",
"former_names": [
{}
],
"gross_tonnage": 220940,
"home_port": "Panama City",
"imo": 9321483,
"kilowatt_power": 58000,
"length": 400,
"length_unit": "m",
"manager_name": "Evergreen Marine Corp",
"mmsi": 477045900,
"name": "EVER GIVEN",
"name_ais": "EVER GIVEN",
"operating_status": "Active",
"owner_name": "Evergreen Marine Corp",
"speed_calculated_avg": 12.4,
"speed_observed_max": 22.1,
"summer_draught": 16.5,
"teu": 23992,
"vessel_subtype": "Motorvrachtschip",
"vessel_type": "Container Ship",
"year_built": 2018
}
]
}
/v1/vessel/{id}
v1
🔒 Auth Required
Get vessel information by MMSI or IMO
Retrieves static vessel data including name, type, dimensions, and registration information for a vessel identified by its MMSI or IMO number
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
232003239 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
mmsiEnum:
mmsi, imo |
Schema:
VesselResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"vessel": {
"breadth": 59,
"breadth_unit": "m",
"builder": "Imabari Shipbuilding",
"call_sign": "H3RC",
"class_society": "American Bureau of Shipping",
"country": "Panama",
"country_code": "PA",
"deadweight_tonnage": 199629,
"draft": 16,
"draft_unit": "m",
"draught_calculated_avg": 13.8,
"draught_observed_max": 16,
"engine_model_name": "string",
"engine_type": 0,
"eni": "02320524",
"former_names": [
{
"name": "EVER GREEN",
"year_until": "2018"
}
],
"gross_tonnage": 220940,
"home_port": "Panama City",
"imo": 9321483,
"kilowatt_power": 58000,
"length": 400,
"length_unit": "m",
"manager_name": "Evergreen Marine Corp",
"mmsi": 477045900,
"name": "EVER GIVEN",
"name_ais": "EVER GIVEN",
"operating_status": "Active",
"owner_name": "Evergreen Marine Corp",
"speed_calculated_avg": 12.4,
"speed_observed_max": 22.1,
"summer_draught": 16.5,
"teu": 23992,
"vessel_subtype": "Motorvrachtschip",
"vessel_type": "Container Ship",
"year_built": 2018
}
}
/v1/vessel/{id}/eta
v1
🔒 Auth Required
Get vessel latest ETA
Retrieves the most recent Estimated Time of Arrival (ETA) reported by the vessel
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
232003239 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
mmsiEnum:
mmsi, imo |
Schema:
VesselETAResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"vesselEta": {
"destination": "SINGAPORE",
"destination_port": "NLRTM",
"draught": 14.5,
"eta": "string",
"imo": 9321483,
"mmsi": 477045900,
"timestamp": "string",
"vessel_name": "EVER GIVEN"
}
}
/v1/vessel/{id}/position
v1
🔒 Auth Required
Get last known vessel position
Retrieves the most recent AIS position report for a vessel, including coordinates, vessel identifiers, and timestamps. Use sat=true to enable satellite AIS fallback when terrestrial data is stale — requires satellite credits.
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
232003239 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
mmsiEnum:
mmsi, imo |
filter.sat
|
boolean | query |
Enable satellite AIS fallback (default: false)
Example:
false |
Schema:
VesselPositionResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
PaymentRequiredErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"vesselPosition": {
"cog": 231.5,
"heading": 230,
"imo": 9321483,
"latitude": 1.2644,
"location": {
"coordinates": [
103.8215,
1.2644
],
"type": "Point"
},
"longitude": 103.8215,
"mmsi": 477045900,
"nav_status": 0,
"processed_timestamp": "string",
"sog": 14.1,
"suspected_glitch": false,
"timestamp": "string",
"vessel_name": "EVER GIVEN"
}
}
/v1/vessels/positions
v1
🔒 Auth Required
Get positions for multiple vessels
Retrieves AIS position data for multiple vessels identified by MMSI or IMO numbers within a specified time range (defaults to past 2 hours). Provide multiple IDs either as a comma-separated list in one filter.ids param, or by repeating filter.ids; both forms (and a mix) are accepted.
| Name | Type | In | Description |
|---|---|---|---|
filter.ids
*
|
string | query |
MMSI or IMO number(s): comma-separated in one param, or repeat filter.ids for multiple
Example:
232003239,246497000 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
mmsiEnum:
mmsi, imo |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Pagination token for retrieving the next page of results |
Schema:
VesselPositionsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"vesselPositions": [
{
"cog": 231.5,
"heading": 230,
"imo": 9321483,
"latitude": 1.2644,
"location": {},
"longitude": 103.8215,
"mmsi": 477045900,
"nav_status": 0,
"processed_timestamp": "string",
"sog": 14.1,
"suspected_glitch": false,
"timestamp": "string",
"vessel_name": "EVER GIVEN"
}
]
}
Vessel Enrichment
more in v1Access classification, ownership, and management data for vessels identified by IMO or MMSI
/v1/vessel/{id}/classification
v1
🔒 Auth Required
Get classification data for a vessel
Retrieves vessel classification data including identification, ownership, certificates, surveys, and technical specifications
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
9121998 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
imoEnum:
mmsi, imo |
Schema:
ClassificationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"classification": {
"certificates": [
{
"certificate": "string",
"code": "string",
"expires": "string",
"extUntil": "string",
"issued": "string",
"term": "string",
"type": "string"
}
],
"classification": {
"classEntryDate": "string",
"classNotationString": "string",
"classNotationStringDesign": "string",
"classNotationStringInOperation": "string",
"classNotationStringMain": "string",
"classNumber": "string",
"classSociety": "string",
"constructionSymbol": "string",
"dateOfLatestStatus": "string",
"dateOfNextSurvey": "string",
"dateOfSurvey": "string",
"dualClass": "string",
"equipmentNumber": "string",
"lastClassificationSociety": "string",
"mainClass": "string",
"mainClassMachinery": "string",
"registerNotationString": "string",
"statusCode": "string",
"statusReason": "string"
},
"collectedAt": "string",
"conditions": [
{
"condition": "string",
"dueDate": "string",
"imposedDate": "string"
}
],
"contributingSources": [
{}
],
"dimensions": {
"bm": 0,
"dm": 0,
"draught": 0,
"dwt": 0,
"grossTon69": 0,
"lbp": 0,
"lengthOverall": 0,
"netTon69": 0
},
"hull": {
"decksNumber": "string"
},
"identification": {
"classStatusString": "string",
"flagCode": "string",
"flagName": "string",
"homePort": "string",
"imoNumber": "string",
"nonClassRelationString": "string",
"officialNumber": "string",
"operationalStatusString": "string",
"purposes": [
{}
],
"register": "string",
"signalLetters": "string",
"typeFormatted": "string",
"vesselId": "string",
"vesselName": "string",
"yearBuilt": 0
},
"imo": 0,
"lastObservedAt": "string",
"machinery": {
"mainPropulsion": "string"
},
"owner": {
"docHolderDnvId": "string",
"docHolderImoNumber": "string",
"docHolderName": "string",
"managerDnvId": "string",
"managerImoNumber": "string",
"managerName": "string",
"ownerDnvId": "string",
"ownerImoNumber": "string",
"ownerName": "string"
},
"sourceUrl": "string",
"sources": {
"certificates": {},
"classification": {},
"collectedAt": {},
"conditions": {},
"dimensions": {},
"hull": {},
"identification": {},
"imo": {},
"lastObservedAt": {},
"machinery": {},
"owner": {},
"sourceUrl": {},
"surveys": {},
"yard": {}
},
"surveys": [
{
"category": "string",
"dueFrom": "string",
"dueTo": "string",
"lastDate": "string",
"location": "string",
"postponed": "string",
"survey": "string"
}
],
"yard": {
"contractedBuilder": "string",
"contractedBuilderBuildNo": "string",
"dateOfBuild": "string",
"hullYardBuildNo": "string",
"hullYardName": "string",
"keelDate": "string"
}
}
}
/v1/vessel/{id}/ownership
v1
🔒 Auth Required
Get ownership data for a vessel
Retrieves ownership and management information for the specified vessel
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
9121998 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
imoEnum:
mmsi, imo |
force_refresh
|
boolean | query | Bypass cache and force a fresh upstream fetch (use sparingly) |
Schema:
types.OwnershipResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"cached_at": "string",
"imo": 0,
"ownership": {
"doc_company": "string",
"doc_company_address": "string",
"imo": 0,
"registered_owner": "string",
"registered_owner_address": "string",
"ship_manager": "string",
"ship_manager_address": "string"
}
}
Vessel Emissions
more in v1Access vessel emissions data including CO2 emissions, fuel consumption, and energy efficiency metrics by vessel or reporting period
/v1/emissions
v1
🔒 Auth Required
List emissions data
Retrieves emissions data with optional filtering by reporting period
| Name | Type | In | Description |
|---|---|---|---|
filter.period
|
integer | query |
Reporting year filter (e.g. 2024)
Example:
2024 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Pagination token for retrieving the next page of results |
Schema:
VesselEmissionsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"emissions": [
{
"co2_emissions_at_berth": 0,
"co2_emissions_on_laden_voyages": 0,
"co2_emissions_total": 0,
"co2_per_distance": 0,
"co2_per_transport_work": 0,
"collected_at": "string",
"distance_through_ice": 0,
"doc_expiry_date": "string",
"doc_issue_date": "string",
"flag_code": "string",
"flag_name": "string",
"fuel_consumption_hfo": 0,
"fuel_consumption_lfo": 0,
"fuel_consumption_lng": 0,
"fuel_consumption_mdo": 0,
"fuel_consumption_mgo": 0,
"fuel_consumption_other": 0,
"fuel_consumption_total": 0,
"fuel_per_distance": 0,
"fuel_per_transport_work": 0,
"home_port": "string",
"ice_class": "string",
"imo": 0,
"monitoring_method_a": "string",
"monitoring_method_b": "string",
"monitoring_method_c": "string",
"monitoring_method_d": "string",
"name": "string",
"port_calls_outside_eu": 0,
"port_calls_within_eu": 0,
"reporting_period": "string",
"source_url": "string",
"technical_efficiency": "string",
"technical_efficiency_value": 0,
"time_at_sea_through_ice": 0,
"total_time_at_sea": 0,
"unique_key": "string",
"verifier_accreditation": "string",
"verifier_address": "string",
"verifier_name": "string",
"vessel_type": "string"
}
],
"nextToken": "string"
}
/v1/vessel/{id}/emissions
v1
🔒 Auth Required
Get emissions data for a vessel
Retrieves emissions reports for the specified vessel including CO2 emissions, fuel consumption, and efficiency metrics
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
1045356 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
imoEnum:
mmsi, imo |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Pagination token for retrieving the next page of results |
Schema:
VesselEmissionsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"emissions": [
{
"co2_emissions_at_berth": 0,
"co2_emissions_on_laden_voyages": 0,
"co2_emissions_total": 0,
"co2_per_distance": 0,
"co2_per_transport_work": 0,
"collected_at": "string",
"distance_through_ice": 0,
"doc_expiry_date": "string",
"doc_issue_date": "string",
"flag_code": "string",
"flag_name": "string",
"fuel_consumption_hfo": 0,
"fuel_consumption_lfo": 0,
"fuel_consumption_lng": 0,
"fuel_consumption_mdo": 0,
"fuel_consumption_mgo": 0,
"fuel_consumption_other": 0,
"fuel_consumption_total": 0,
"fuel_per_distance": 0,
"fuel_per_transport_work": 0,
"home_port": "string",
"ice_class": "string",
"imo": 0,
"monitoring_method_a": "string",
"monitoring_method_b": "string",
"monitoring_method_c": "string",
"monitoring_method_d": "string",
"name": "string",
"port_calls_outside_eu": 0,
"port_calls_within_eu": 0,
"reporting_period": "string",
"source_url": "string",
"technical_efficiency": "string",
"technical_efficiency_value": 0,
"time_at_sea_through_ice": 0,
"total_time_at_sea": 0,
"unique_key": "string",
"verifier_accreditation": "string",
"verifier_address": "string",
"verifier_name": "string",
"vessel_type": "string"
}
],
"nextToken": "string"
}
Safety & Compliance
more in v1Retrieve marine casualty records, port state control inspections, and inspection deficiency details for vessels
/v1/vessel/{id}/casualties
v1
🔒 Auth Required
Get marine casualties involving a vessel
Retrieves marine casualty records involving the specified vessel
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
9321483 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
imoEnum:
mmsi, imo |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Pagination token for retrieving the next page of results |
Schema:
MarineCasualtiesResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"casualties": [
{
"atCoding": [
"string"
],
"casualtyReportNr": "string",
"cfCoding": [
"string"
],
"collectedAt": "string",
"competentAuthority": [
"string"
],
"dateOfOccurrence": "string",
"deviation": [
"string"
],
"eventType": [
"string"
],
"finishedInvestigation": false,
"imoNr": [
"string"
],
"interimReport": false,
"investigatingState": "string",
"livesLostTotal": "string",
"nameOfShip": [
"string"
],
"occurrenceSeverity": "string",
"occurrenceUuid": "string",
"occurrenceWithPersons": [
"string"
],
"occurrenceWithShips": [
"string"
],
"peopleInjuredTotal": "string",
"pollution": false,
"shipCraftType": [
"string"
],
"srCoding": [
"string"
]
}
],
"nextToken": "string"
}
/v1/vessel/{id}/inspections
v1
🔒 Auth Required
Get inspection records for a vessel
Retrieves port state control inspection records for the specified vessel
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
9121998 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
imoEnum:
mmsi, imo |
force_refresh
|
boolean | query | Bypass cache and force a fresh upstream fetch (use sparingly) |
Schema:
types.InspectionsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"cached_at": "string",
"imo": 0,
"inspection_count": 0,
"inspections": [
{
"authority": "string",
"deficiencies": 0,
"detail_id": "string",
"detained": false,
"imo": 0,
"inspection_date": "string",
"inspection_type": "string",
"mou_region": "string",
"port": "string"
}
]
}
/v1/vessel/{id}/inspections/{detail_id}
v1
🔒 Auth Required
Get inspection detail
Retrieves detailed inspection information including deficiencies for a specific inspection
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
9121998 |
detail_id
*
|
string | path |
Inspection detail ID
Example:
6352425 |
filter.idType
*
|
string | query |
Identifier type: 'mmsi' or 'imo'
Example:
imoEnum:
mmsi, imo |
Schema:
types.InspectionDetailResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"cached_at": "string",
"detail_id": "string",
"imo": 0,
"inspection_detail": {
"authority": "string",
"deficiencies": [
{
"category": "string",
"count": 0,
"deficiency": "string"
}
],
"deficiency_count": 0,
"detail_id": "string",
"detained": false,
"detention_grounds": [
{
"category": "string",
"count": 0,
"deficiency": "string"
}
],
"imo": 0,
"inspection_date": "string",
"inspection_type": "string",
"mou_region": "string",
"port": "string"
}
}
Ports
more in v1Search world port index data by location, name, or geographic area
/v1/location/ports/bounding-box
v1
🔒 Auth Required
Get Ports within a bounding box
Retrieves Ports within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees
| Name | Type | In | Description |
|---|---|---|---|
filter.lonLeft
*
|
number | query |
Longitude of the left (western) edge of the bounding box
Example:
4 |
filter.lonRight
*
|
number | query |
Longitude of the right (eastern) edge of the bounding box
Example:
5 |
filter.latBottom
*
|
number | query |
Latitude of the bottom (southern) edge of the bounding box
Example:
51 |
filter.latTop
*
|
number | query |
Latitude of the top (northern) edge of the bounding box
Example:
52 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"ports": [
{
"anchorage_depth": 20,
"anchorage_depth_unit": "m",
"cargo_handling_depth": 18,
"cargo_handling_depth_unit": "m",
"channel_depth": 23,
"channel_depth_unit": "m",
"country": {},
"garbage_disposal": true,
"harbor_size": "Large",
"harbor_type": "CN",
"harbor_use": "CARGO",
"has_drydock": true,
"latitude": 1.2644,
"location": {},
"longitude": 103.8215,
"max_vessel_beam": 60,
"max_vessel_beam_unit": "m",
"max_vessel_draft": 16,
"max_vessel_draft_unit": "m",
"max_vessel_length": 400,
"max_vessel_length_unit": "m",
"medical_facilities": true,
"name": "Singapore",
"navigation_area": "XI",
"pilotage_available": true,
"pilotage_compulsory": true,
"port_security": true,
"region_name": "Southeast Asia",
"repair_capability": "Major",
"shelter": "Excellent",
"size": "Large",
"supply_diesel": true,
"supply_fuel": true,
"supply_water": true,
"traffic_separation_scheme": true,
"tugs_available": true,
"type": "Seaport",
"unlo_code": "SGSIN",
"vessel_traffic_service": true
}
]
}
/v1/location/ports/radius
v1
🔒 Auth Required
Get Ports within a radius
Retrieves Ports within a specified radius of a given point
| Name | Type | In | Description |
|---|---|---|---|
filter.longitude
*
|
number | query |
Longitude of the center point
Example:
4.5 |
filter.latitude
*
|
number | query |
Latitude of the center point
Example:
51.5 |
filter.radius
*
|
number | query |
Search radius in meters (max 100,000 = 100 km)
Example:
100000 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"ports": [
{
"anchorage_depth": 20,
"anchorage_depth_unit": "m",
"cargo_handling_depth": 18,
"cargo_handling_depth_unit": "m",
"channel_depth": 23,
"channel_depth_unit": "m",
"country": {},
"garbage_disposal": true,
"harbor_size": "Large",
"harbor_type": "CN",
"harbor_use": "CARGO",
"has_drydock": true,
"latitude": 1.2644,
"location": {},
"longitude": 103.8215,
"max_vessel_beam": 60,
"max_vessel_beam_unit": "m",
"max_vessel_draft": 16,
"max_vessel_draft_unit": "m",
"max_vessel_length": 400,
"max_vessel_length_unit": "m",
"medical_facilities": true,
"name": "Singapore",
"navigation_area": "XI",
"pilotage_available": true,
"pilotage_compulsory": true,
"port_security": true,
"region_name": "Southeast Asia",
"repair_capability": "Major",
"shelter": "Excellent",
"size": "Large",
"supply_diesel": true,
"supply_fuel": true,
"supply_water": true,
"traffic_separation_scheme": true,
"tugs_available": true,
"type": "Seaport",
"unlo_code": "SGSIN",
"vessel_traffic_service": true
}
]
}
/v1/port/{unlocode}
v1
🔒 Auth Required
Get Port by UNLOCODE
Retrieves port details by its UN/LOCODE (e.g., NLRTM for Rotterdam, SGSIN for Singapore)
| Name | Type | In | Description |
|---|---|---|---|
unlocode
*
|
string | path |
UN/LOCODE of the port
Example:
NLRTM |
Schema:
PortResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"port": {
"anchorage_depth": 20,
"anchorage_depth_unit": "m",
"cargo_handling_depth": 18,
"cargo_handling_depth_unit": "m",
"channel_depth": 23,
"channel_depth_unit": "m",
"country": {
"code": "SG",
"name": "Singapore"
},
"garbage_disposal": true,
"harbor_size": "Large",
"harbor_type": "CN",
"harbor_use": "CARGO",
"has_drydock": true,
"latitude": 1.2644,
"location": {
"coordinates": [
103.8215,
1.2644
],
"type": "Point"
},
"longitude": 103.8215,
"max_vessel_beam": 60,
"max_vessel_beam_unit": "m",
"max_vessel_draft": 16,
"max_vessel_draft_unit": "m",
"max_vessel_length": 400,
"max_vessel_length_unit": "m",
"medical_facilities": true,
"name": "Singapore",
"navigation_area": "XI",
"pilotage_available": true,
"pilotage_compulsory": true,
"port_security": true,
"region_name": "Southeast Asia",
"repair_capability": "Major",
"shelter": "Excellent",
"size": "Large",
"supply_diesel": true,
"supply_fuel": true,
"supply_water": true,
"traffic_separation_scheme": true,
"tugs_available": true,
"type": "Seaport",
"unlo_code": "SGSIN",
"vessel_traffic_service": true
}
}
/v1/port/{unlocode}/inbound
v1
🔒 Auth Required
Get Inbound Vessels for Port
Retrieves vessels heading to a specific port within an ETA window
| Name | Type | In | Description |
|---|---|---|---|
unlocode
*
|
string | path |
UN/LOCODE of the destination port
Example:
DEEME |
filter.etaFrom
|
string | query | Start of ETA arrival window in RFC3339 format (defaults to now) |
filter.etaTo
|
string | query | End of ETA arrival window in RFC3339 format (defaults to 72 hours ahead) |
time.from
|
string | query | Report freshness start (defaults to 24 hours ago) |
time.to
|
string | query | Report freshness end (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortInboundResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"vesselETAs": [
{
"destination": "SINGAPORE",
"destination_port": "NLRTM",
"draught": 14.5,
"eta": "string",
"imo": 9321483,
"mmsi": 477045900,
"timestamp": "string",
"vessel_name": "EVER GIVEN"
}
]
}
/v1/search/ports
v1
🔒 Auth Required
Search for Ports
Retrieves a list of ports matching the given filters. At least one filter parameter is required.
| Name | Type | In | Description |
|---|---|---|---|
filter.name
|
string | query |
Name of the port
Example:
Rotterdam |
filter.country
|
array | query |
ISO 2-letter country code(s) or country name(s). Repeat the parameter to match multiple.
Example:
NL |
filter.type
|
array | query |
Port type classification(s) (case-insensitive). Repeat the parameter to match multiple. Note: not all ports have a type assigned.
Example:
Port |
filter.size
|
array | query |
Port size classification(s). Repeat the parameter to match multiple.
Example:
Large |
filter.region
|
string | query |
Geographic region name (partial match)
Example:
Europe |
filter.harborSize
|
array | query |
Harbor size classification(s). Repeat the parameter to match multiple.
Example:
Large |
filter.harborUse
|
array | query |
Primary harbor use(s). Repeat the parameter to match multiple.
Example:
CARGO |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
FindPortsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"ports": [
{
"anchorage_depth": 20,
"anchorage_depth_unit": "m",
"cargo_handling_depth": 18,
"cargo_handling_depth_unit": "m",
"channel_depth": 23,
"channel_depth_unit": "m",
"country": {},
"garbage_disposal": true,
"harbor_size": "Large",
"harbor_type": "CN",
"harbor_use": "CARGO",
"has_drydock": true,
"latitude": 1.2644,
"location": {},
"longitude": 103.8215,
"max_vessel_beam": 60,
"max_vessel_beam_unit": "m",
"max_vessel_draft": 16,
"max_vessel_draft_unit": "m",
"max_vessel_length": 400,
"max_vessel_length_unit": "m",
"medical_facilities": true,
"name": "Singapore",
"navigation_area": "XI",
"pilotage_available": true,
"pilotage_compulsory": true,
"port_security": true,
"region_name": "Southeast Asia",
"repair_capability": "Major",
"shelter": "Excellent",
"size": "Large",
"supply_diesel": true,
"supply_fuel": true,
"supply_water": true,
"traffic_separation_scheme": true,
"tugs_available": true,
"type": "Seaport",
"unlo_code": "SGSIN",
"vessel_traffic_service": true
}
]
}
Port Events
more in v1Access port call information including vessel arrivals, departures, and current port activity
/v1/portevents
v1
🔒 Auth Required
Get Port Events in a time range
Get Port Events, such as Arrivals and Departures, in a time range with optional filters
| Name | Type | In | Description |
|---|---|---|---|
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
filter.country
|
string | query |
Filter by port country (case-insensitive)
Example:
Singapore |
filter.unlocode
|
string | query |
Filter by port UN/LOCODE
Example:
SGSIN |
filter.eventType
|
string | query |
Filter by event type
Enum:
arrival, departure, all |
filter.vesselName
|
string | query |
Filter by vessel name (full-text search)
Example:
EVER GIVEN |
filter.portName
|
string | query |
Filter by port name (full-text search)
Example:
Rotterdam |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortEventsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"nextToken": "string",
"portEvents": [
{
"event": "Arrival",
"port": {},
"timestamp": "string",
"vessel": {}
}
]
}
/v1/portevents/port/{unlocode}
v1
🔒 Auth Required
Get Port Events by port UNLOCODE
Get Port Events, such as Arrivals and Departures by supplying the port UN/LOCODE (e.g., NLRTM for Rotterdam, SGSIN for Singapore)
| Name | Type | In | Description |
|---|---|---|---|
unlocode
*
|
string | path |
UN/LOCODE of the port
Example:
NLRTM |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortEventsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"nextToken": "string",
"portEvents": [
{
"event": "Arrival",
"port": {},
"timestamp": "string",
"vessel": {}
}
]
}
/v1/portevents/ports
v1
🔒 Auth Required
Get Port Events by port name
Get Port Events, such as Arrivals and Departures by supplying the port name
| Name | Type | In | Description |
|---|---|---|---|
filter.portName
*
|
string | query |
Port name
Example:
Rotterdam |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortEventsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"nextToken": "string",
"portEvents": [
{
"event": "Arrival",
"port": {},
"timestamp": "string",
"vessel": {}
}
]
}
/v1/portevents/vessel/{id}
v1
🔒 Auth Required
Get Port Events by Vessel ID
Get all port events (arrivals and departures) for a vessel identified by MMSI or IMO, with optional filtering by event type and time range
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
232003239 |
filter.idType
*
|
string | query |
Identifier type (mmsi or imo)
Enum:
mmsi, imo |
filter.eventType
|
string | query |
Filter by event type
Default:
allEnum:
arrival, departure, all |
filter.sortOrder
|
string | query |
Sort order by timestamp
Default:
descEnum:
asc, desc |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortEventsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"nextToken": "string",
"portEvents": [
{
"event": "Arrival",
"port": {},
"timestamp": "string",
"vessel": {}
}
]
}
/v1/portevents/vessel/{id}/last
v1
🔒 Auth Required
Get Last Port Event by ID
Get the most recent port event (arrival or departure) for a vessel identified by MMSI or IMO
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
MMSI or IMO number
Example:
232003239 |
filter.idType
*
|
string | query |
Identifier type (mmsi or imo)
Enum:
mmsi, imo |
Schema:
PortEventResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"portEvent": {
"event": "Arrival",
"port": {
"country": "Singapore",
"name": "Singapore",
"unlo_code": "SGSIN"
},
"timestamp": "string",
"vessel": {
"imo": 9321483,
"mmsi": 477045900,
"name": "EVER GIVEN"
}
}
}
/v1/portevents/vessels
v1
🔒 Auth Required
Get Port Events by vessel name
Get Port Events by vessel name
| Name | Type | In | Description |
|---|---|---|---|
filter.vesselName
*
|
string | query |
Vessel name
Example:
strangford 2 |
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 2 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
PortEventsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"_meta": {
"requestedIdType": "string",
"resolvedId": 0,
"resolvedIdType": "string",
"suggestedIdType": "string"
},
"nextToken": "string",
"portEvents": [
{
"event": "Arrival",
"port": {},
"timestamp": "string",
"vessel": {}
}
]
}
Navtex Messages
more in v1more in v2Query NAVTEX maritime safety broadcasts and navigational warnings
/v1/navtex
v1
🔒 Auth Required
Get Navtex messages in a time range
Get Navtex messages in a time range
| Name | Type | In | Description |
|---|---|---|---|
time.from
|
string | query | Start timestamp in RFC3339 format (defaults to 24 hours ago) |
time.to
|
string | query | End timestamp in RFC3339 format (defaults to current time) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
NavtexMessagesResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"navtexMessages": [
{
"issuing_office": "TOKYO",
"label": "NAVIGATIONAL WARNING",
"lines": [
"string"
],
"metarea_coordinator": "Japan",
"metarea_id": "XI",
"metarea_name": "South China Sea",
"metarea_region": "Asia Pacific",
"metarea_stations": [
{}
],
"raw_content": "string",
"timestamp": "string",
"wmo_header": "WWNP40"
}
],
"nextToken": "string"
}
/v2/navtex/metarea
v2
🔒 Auth Required
Get METAREA meteorological warnings
Get METAREA (meteorological) NAVTEX warnings, filterable by area, coordinator, label, and free-text. Same underlying data as /v1/navtex with clearer naming. Unlike v1, the time range is optional — omit time.from/time.to to get all messages.
| Name | Type | In | Description |
|---|---|---|---|
filter.metarea_id
|
string | query |
Filter by METAREA id(s); comma-separated or the parameter repeated
Example:
11,8N |
filter.coordinator
|
string | query |
Filter by coordinating country/countries; comma-separated or the parameter repeated
Example:
Japan |
filter.label
|
string | query |
Filter by message type (substring match)
Example:
HIGH SEAS FORECAST |
filter.q
|
string | query |
Free-text search over message content
Example:
typhoon |
time.from
|
string | query | Start timestamp in RFC3339 (optional; omit for no lower bound) |
time.to
|
string | query | End timestamp in RFC3339 (optional; omit for no upper bound) |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
NavtexMessagesResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"navtexMessages": [
{
"issuing_office": "TOKYO",
"label": "NAVIGATIONAL WARNING",
"lines": [
"string"
],
"metarea_coordinator": "Japan",
"metarea_id": "XI",
"metarea_name": "South China Sea",
"metarea_region": "Asia Pacific",
"metarea_stations": [
{}
],
"raw_content": "string",
"timestamp": "string",
"wmo_header": "WWNP40"
}
],
"nextToken": "string"
}
/v2/navtex/navarea
v2
🔒 Auth Required
Get NAVAREA navigational warnings
Returns NAVAREA navigational-hazard warnings. Defaults to in_force warnings only; use filter.status=all for every state, filter.status=<state> for one state, or filter.include=expired,cancelled to add states to the in_force set. SAFETY: for situational awareness only — not a substitute for official broadcasts.
| Name | Type | In | Description |
|---|---|---|---|
filter.status
|
string | query |
Lifecycle filter: omit for in_force only, 'all' for every state, or a single state
Enum:
in_force, expired, cancelled, cancellation, withdrawn, all |
filter.include
|
string | query |
Extra states to include alongside in_force; comma-separated or the parameter repeated
Example:
expired,cancelled |
filter.navarea_id
|
string | query |
Filter by NAVAREA(s); comma-separated or the parameter repeated
Example:
IV,XII |
filter.coordinator
|
string | query |
Filter by coordinating country/countries; comma-separated or the parameter repeated
Example:
United States |
filter.year
|
integer | query |
Filter by issue year
Example:
2026 |
filter.issued_from
|
string | query |
Issued on/after (RFC3339)
Example:
2026-01-01T00:00:00Z |
filter.issued_to
|
string | query | Issued on/before (RFC3339) |
filter.q
|
string | query |
Free-text search over area and body
Example:
exercise |
filter.near
|
string | query |
Warnings within radius of a point: lat,lon,radius_nm
Example:
24.5,-83.1,50 |
filter.bbox
|
string | query |
Warnings intersecting a bounding box: minLat,minLon,maxLat,maxLon
Example:
10,-90,30,-60 |
filter.sort
|
string | query |
Sort: field:dir
Enum:
first_seen_at:desc, first_seen_at:asc, issue_date:desc, issue_date:asc, last_seen_at:desc, last_seen_at:asc, navarea_id:asc, navarea_id:desc |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
NavareaWarningsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"disclaimer": "string",
"nextToken": "string",
"warnings": [
{
"area": "Gulf of Mexico",
"body": "string",
"cancelled_by_ref": "string",
"cancels_ref": "string",
"coordinates": [
{}
],
"coordinator": "United States",
"document_date": "string",
"expires_at": "string",
"first_seen_at": "string",
"issue_date": "string",
"last_seen_at": "string",
"navarea_id": "IV",
"raw_content": "string",
"series": "navarea",
"source": "nga_msi",
"status": "in_force",
"status_basis": "official",
"status_reason": "active",
"warning_number": "237/26",
"year": 2026
}
]
}
Navigation Infrastructure
more in v1Locate maritime navigation aids and infrastructure including DGPS stations, light aids, MODUs, and radio beacons by geographic coordinates or name
/v1/location/dgps/bounding-box
v1
🔒 Auth Required
Get DGPS Stations within a bounding box
Retrieves Dgps stations within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees
| Name | Type | In | Description |
|---|---|---|---|
filter.lonLeft
*
|
number | query |
Longitude of the left (western) edge of the bounding box
Example:
7 |
filter.lonRight
*
|
number | query |
Longitude of the right (eastern) edge of the bounding box
Example:
9 |
filter.latBottom
*
|
number | query |
Latitude of the bottom (southern) edge of the bounding box
Example:
55 |
filter.latTop
*
|
number | query |
Latitude of the top (northern) edge of the bounding box
Example:
56 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
DGPSStationsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"dgpsStations": [
{
"aid_type": "DGPS",
"delete_flag": "string",
"feature_number": 1234.5,
"frequency": 290,
"geopolitical_heading": "UNITED STATES",
"location": {},
"name": "Cape Henry DGPS",
"notice_number": 12,
"notice_week": "15",
"notice_year": "2024",
"position": "36°55.5'N 76°00.3'W",
"post_note": "string",
"preceding_note": "string",
"range": 100,
"region_heading": "EAST COAST",
"remarks": "string",
"remove_from_list": "string",
"station_id": "852",
"transfer_rate": 200,
"volume_number": "PUB 117"
}
],
"nextToken": "string"
}
/v1/location/dgps/radius
v1
🔒 Auth Required
Get DGPS Stations within a radius
Retrieves Dgps stations within a specified radius of a given point
| Name | Type | In | Description |
|---|---|---|---|
filter.longitude
*
|
number | query |
Longitude of the center point
Example:
8.084 |
filter.latitude
*
|
number | query |
Latitude of the center point
Example:
55.558 |
filter.radius
*
|
number | query |
Search radius in meters (max 100,000 = 100 km)
Example:
10000 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
DGPSStationsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"dgpsStations": [
{
"aid_type": "DGPS",
"delete_flag": "string",
"feature_number": 1234.5,
"frequency": 290,
"geopolitical_heading": "UNITED STATES",
"location": {},
"name": "Cape Henry DGPS",
"notice_number": 12,
"notice_week": "15",
"notice_year": "2024",
"position": "36°55.5'N 76°00.3'W",
"post_note": "string",
"preceding_note": "string",
"range": 100,
"region_heading": "EAST COAST",
"remarks": "string",
"remove_from_list": "string",
"station_id": "852",
"transfer_rate": 200,
"volume_number": "PUB 117"
}
],
"nextToken": "string"
}
/v1/location/lightaids/bounding-box
v1
🔒 Auth Required
Get Light Aids to Navigation within a bounding box
Retrieves Light Aids to Navigation within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees
| Name | Type | In | Description |
|---|---|---|---|
filter.lonLeft
*
|
number | query |
Longitude of the left (western) edge of the bounding box
Example:
4 |
filter.lonRight
*
|
number | query |
Longitude of the right (eastern) edge of the bounding box
Example:
5 |
filter.latBottom
*
|
number | query |
Latitude of the bottom (southern) edge of the bounding box
Example:
51 |
filter.latTop
*
|
number | query |
Latitude of the top (northern) edge of the bounding box
Example:
52 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
LightAidsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"lightAids": [
{
"aid_type": "Light",
"characteristic": "Fl W 7.5s",
"characteristic_number": 0,
"delete_flag": "string",
"feature_number": "590",
"geopolitical_heading": "UNITED STATES",
"height_feet_meters": "192ft 59m",
"local_heading": "Cape Hatteras",
"location": {},
"name": "Cape Hatteras Light",
"notice_number": 0,
"notice_week": "string",
"notice_year": "string",
"position": "35°15.1'N 75°31.6'W",
"post_note": "string",
"preceding_note": "string",
"range": "24",
"region_heading": "EAST COAST",
"remarks": "string",
"remove_from_list": "string",
"structure": "Black and white spiral bands",
"subregion_heading": "North Carolina",
"volume_number": "PUB 110"
}
],
"nextToken": "string"
}
/v1/location/lightaids/radius
v1
🔒 Auth Required
Get Light Aids to Navigation within a radius
Retrieves Light Aids to Navigation within a specified radius of a given point
| Name | Type | In | Description |
|---|---|---|---|
filter.longitude
*
|
number | query |
Longitude of the center point
Example:
4.5 |
filter.latitude
*
|
number | query |
Latitude of the center point
Example:
51.5 |
filter.radius
*
|
number | query |
Search radius in meters (max 100,000 = 100 km)
Example:
100000 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
LightAidsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"lightAids": [
{
"aid_type": "Light",
"characteristic": "Fl W 7.5s",
"characteristic_number": 0,
"delete_flag": "string",
"feature_number": "590",
"geopolitical_heading": "UNITED STATES",
"height_feet_meters": "192ft 59m",
"local_heading": "Cape Hatteras",
"location": {},
"name": "Cape Hatteras Light",
"notice_number": 0,
"notice_week": "string",
"notice_year": "string",
"position": "35°15.1'N 75°31.6'W",
"post_note": "string",
"preceding_note": "string",
"range": "24",
"region_heading": "EAST COAST",
"remarks": "string",
"remove_from_list": "string",
"structure": "Black and white spiral bands",
"subregion_heading": "North Carolina",
"volume_number": "PUB 110"
}
],
"nextToken": "string"
}
/v1/location/modu/bounding-box
v1
🔒 Auth Required
Get Mobile Offshore Drilling Units within a bounding box
Retrieves Mobile Offshore Drilling Units within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees
| Name | Type | In | Description |
|---|---|---|---|
filter.lonLeft
*
|
number | query |
Longitude of the left (western) edge of the bounding box
Example:
-89 |
filter.lonRight
*
|
number | query |
Longitude of the right (eastern) edge of the bounding box
Example:
-88 |
filter.latBottom
*
|
number | query |
Latitude of the bottom (southern) edge of the bounding box
Example:
28 |
filter.latTop
*
|
number | query |
Latitude of the top (northern) edge of the bounding box
Example:
29 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
MODUsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"modus": [
{
"date": "string",
"distance": 0,
"latitude": 28.7381,
"location": {},
"longitude": -88.3659,
"name": "DEEPWATER HORIZON",
"navigation_area": "IV",
"position": "Gulf of Mexico",
"region": 8,
"rig_status": "Drilling",
"special_status": "string",
"sub_region": 81
}
],
"nextToken": "string"
}
/v1/location/modu/radius
v1
🔒 Auth Required
Get Mobile Offshore Drilling Units within a radius
Retrieves Mobile Offshore Drilling Units within a specified radius of a given point
| Name | Type | In | Description |
|---|---|---|---|
filter.longitude
*
|
number | query |
Longitude of the center point
Example:
-88.5 |
filter.latitude
*
|
number | query |
Latitude of the center point
Example:
28.2 |
filter.radius
*
|
number | query |
Search radius in meters (max 100,000 = 100 km)
Example:
50000 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
MODUsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"modus": [
{
"date": "string",
"distance": 0,
"latitude": 28.7381,
"location": {},
"longitude": -88.3659,
"name": "DEEPWATER HORIZON",
"navigation_area": "IV",
"position": "Gulf of Mexico",
"region": 8,
"rig_status": "Drilling",
"special_status": "string",
"sub_region": 81
}
],
"nextToken": "string"
}
/v1/location/radiobeacons/bounding-box
v1
🔒 Auth Required
Get Radio Beacons within a bounding box
Retrieves Radio Beacons within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees
| Name | Type | In | Description |
|---|---|---|---|
filter.lonLeft
*
|
number | query |
Longitude of the left (western) edge of the bounding box
Example:
-1 |
filter.lonRight
*
|
number | query |
Longitude of the right (eastern) edge of the bounding box
Example:
1 |
filter.latBottom
*
|
number | query |
Latitude of the bottom (southern) edge of the bounding box
Example:
50 |
filter.latTop
*
|
number | query |
Latitude of the top (northern) edge of the bounding box
Example:
51 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
RadioBeaconsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"radioBeacons": [
{
"aid_type": "RBn",
"characteristic": "A (.--)",
"delete_flag": "string",
"feature_number": 456,
"frequency": "286 kHz",
"geopolitical_heading": "UNITED STATES",
"location": {},
"name": "Ambrose Light",
"notice_number": 0,
"notice_week": "string",
"notice_year": "string",
"position": "40°27.1'N 73°49.5'W",
"post_note": "string",
"preceding_note": "string",
"range": "20",
"region_heading": "EAST COAST",
"remove_from_list": "string",
"sequence_text": "string",
"station_remark": "string",
"volume_number": "PUB 117"
}
]
}
/v1/location/radiobeacons/radius
v1
🔒 Auth Required
Get Radio Beacons within a radius
Retrieves Radio Beacons within a specified radius of a given point
| Name | Type | In | Description |
|---|---|---|---|
filter.longitude
*
|
number | query |
Longitude of the center point
Example:
-0.1 |
filter.latitude
*
|
number | query |
Latitude of the center point
Example:
50.8 |
filter.radius
*
|
number | query |
Search radius in meters (max 100,000 = 100 km)
Example:
100000 |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
RadioBeaconsWithinLocationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"radioBeacons": [
{
"aid_type": "RBn",
"characteristic": "A (.--)",
"delete_flag": "string",
"feature_number": 456,
"frequency": "286 kHz",
"geopolitical_heading": "UNITED STATES",
"location": {},
"name": "Ambrose Light",
"notice_number": 0,
"notice_week": "string",
"notice_year": "string",
"position": "40°27.1'N 73°49.5'W",
"post_note": "string",
"preceding_note": "string",
"range": "20",
"region_heading": "EAST COAST",
"remove_from_list": "string",
"sequence_text": "string",
"station_remark": "string",
"volume_number": "PUB 117"
}
]
}
/v1/search/dgps
v1
🔒 Auth Required
Search for DGPS Stations
Retrieves a list of DGPS stations for the given query parameters
| Name | Type | In | Description |
|---|---|---|---|
filter.name
*
|
string | query |
Name of the DGPS station
Example:
Hammer Odde |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
FindDGPSStationsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"dgpsStations": [
{
"aid_type": "DGPS",
"delete_flag": "string",
"feature_number": 1234.5,
"frequency": 290,
"geopolitical_heading": "UNITED STATES",
"location": {},
"name": "Cape Henry DGPS",
"notice_number": 12,
"notice_week": "15",
"notice_year": "2024",
"position": "36°55.5'N 76°00.3'W",
"post_note": "string",
"preceding_note": "string",
"range": 100,
"region_heading": "EAST COAST",
"remarks": "string",
"remove_from_list": "string",
"station_id": "852",
"transfer_rate": 200,
"volume_number": "PUB 117"
}
],
"nextToken": "string"
}
/v1/search/lightaids
v1
🔒 Auth Required
Search for Light Aids to Navigation
Retrieves a list of Light Aids to Navigation for the given query parameters
| Name | Type | In | Description |
|---|---|---|---|
filter.name
*
|
string | query |
Name of the Light Aid
Example:
Creach |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
FindLightAidsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"lightAids": [
{
"aid_type": "Light",
"characteristic": "Fl W 7.5s",
"characteristic_number": 0,
"delete_flag": "string",
"feature_number": "590",
"geopolitical_heading": "UNITED STATES",
"height_feet_meters": "192ft 59m",
"local_heading": "Cape Hatteras",
"location": {},
"name": "Cape Hatteras Light",
"notice_number": 0,
"notice_week": "string",
"notice_year": "string",
"position": "35°15.1'N 75°31.6'W",
"post_note": "string",
"preceding_note": "string",
"range": "24",
"region_heading": "EAST COAST",
"remarks": "string",
"remove_from_list": "string",
"structure": "Black and white spiral bands",
"subregion_heading": "North Carolina",
"volume_number": "PUB 110"
}
],
"nextToken": "string"
}
/v1/search/modus
v1
🔒 Auth Required
Search for MODUs
Retrieves a list of MODUs for the given query parameters
| Name | Type | In | Description |
|---|---|---|---|
filter.name
*
|
string | query |
Name of the MODU
Example:
ABAN |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
FindMODUsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"modus": [
{
"date": "string",
"distance": 0,
"latitude": 28.7381,
"location": {},
"longitude": -88.3659,
"name": "DEEPWATER HORIZON",
"navigation_area": "IV",
"position": "Gulf of Mexico",
"region": 8,
"rig_status": "Drilling",
"special_status": "string",
"sub_region": 81
}
],
"nextToken": "string"
}
/v1/search/radiobeacons
v1
🔒 Auth Required
Search for Radio Beacons
Retrieves a list of Radio Beacons for the given query parameters
| Name | Type | In | Description |
|---|---|---|---|
filter.name
*
|
string | query |
Name of the Radio Beacon
Example:
Brighton |
pagination.limit
|
integer | query |
Maximum number of items to return, must be between 1 and 50
Default:
20 |
pagination.nextToken
|
string | query | Token for next page |
Schema:
FindRadioBeaconsResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"nextToken": "string",
"radioBeacons": [
{
"aid_type": "RBn",
"characteristic": "A (.--)",
"delete_flag": "string",
"feature_number": 456,
"frequency": "286 kHz",
"geopolitical_heading": "UNITED STATES",
"location": {},
"name": "Ambrose Light",
"notice_number": 0,
"notice_week": "string",
"notice_year": "string",
"position": "40°27.1'N 73°49.5'W",
"post_note": "string",
"preceding_note": "string",
"range": "20",
"region_heading": "EAST COAST",
"remove_from_list": "string",
"sequence_text": "string",
"station_remark": "string",
"volume_number": "PUB 117"
}
]
}
WebSocket
more in v1Real-time event streaming via WebSocket. Connect to receive events as they occur instead of via webhook callbacks.
/v1/ws
v1
🔒 Auth Required
WebSocket event stream
Connect via WebSocket to receive real-time notification events. The notification must have websocket=true. Authenticate with the Authorization header on the upgrade request. Events arrive as JSON EventEnvelope text frames. The server pings every 30s; standard WebSocket libraries answer automatically. Server-initiated close codes: 4000 ping timeout (no pong for 40s — keep the read loop responsive and reconnect with backoff), 4001 replaced by a newer connection for this notification (only one connection per notification; the newest wins), 4002 notification deleted, deactivated, or websocket delivery disabled (do not reconnect until it is re-enabled), 1013 connection limit reached (retry later), 1012 server restart on deploy (reconnect immediately). Events emitted while no client is connected are discarded, there is no replay.
| Name | Type | In | Description |
|---|---|---|---|
notification_id
*
|
string | query |
Notification ID (must have websocket delivery enabled)
Example:
550e8400-e29b-41d4-a716-446655440000 |
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
/v1/ws/advanced
v1
🔒 Auth Required
Advanced WebSocket event stream
Connect via WebSocket to receive real-time events from an advanced notification. The notification must have websocket=true, be active (409, code notification_inactive), and have prefillStatus "ready" (409, code prefill_pending, with a Retry-After header). Authenticate with the Authorization header on the upgrade request. Events arrive as JSON EventEnvelope text frames. The server pings every 30s; standard WebSocket libraries answer automatically. Server-initiated close codes: 4000 ping timeout (no pong for 40s — keep the read loop responsive and reconnect with backoff), 4001 replaced by a newer connection for this notification (only one connection per notification; the newest wins), 4002 notification deleted, deactivated, or websocket delivery disabled (do not reconnect until it is re-enabled; the close reason says which), 1013 connection limit reached (retry later), 1012 server restart on deploy (reconnect immediately). Events emitted while no client is connected are discarded, there is no replay.
| Name | Type | In | Description |
|---|---|---|---|
name
*
|
string | query |
Advanced notification name (must have websocket delivery enabled)
Example:
europe_registration |
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
ConflictErrorResponse
Notifications
more in v1Create and manage vessel notification configurations. Each notification watches a set of vessels and delivers events via webhook and/or WebSocket.
/v1/notifications
v1
🔒 Auth Required
List notifications
List all notification configurations for the authenticated user
No parameters
Schema:
NotificationListResponse
Schema:
AuthenticationErrorResponse
Schema:
InternalServerErrorResponse
{
"notifications": [
{
"active": true,
"createdAt": "2026-03-27T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"port.arrival",
"position.update"
],
"geofence": {
"latBottom": 51.8,
"latTop": 52.1,
"lonLeft": 3.5,
"lonRight": 4.5
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"imos": [
9321483,
9472440
],
"mmsis": [
477045900
],
"name": "My fleet alerts",
"speedThresholdKnots": 0.5,
"updatedAt": "2026-03-27T12:00:00Z",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
]
}
/v1/notifications
v1
🔒 Auth Required
Create notification
Create a new notification to watch vessels and receive events via webhook and/or WebSocket
| Name | Type | In | Description |
|---|---|---|---|
body
*
|
CreateNotificationRequest
|
body | Notification configuration |
Request Body (CreateNotificationRequest)
{
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"port.arrival",
"position.update"
],
"geofence": {
"latBottom": 51.8,
"latTop": 52.1,
"lonLeft": 3.5,
"lonRight": 4.5
},
"imos": [
9321483,
9472440
],
"mmsis": [
477045900
],
"name": "My fleet alerts",
"speedThresholdKnots": 0.5,
"webhookSecret": "my-secret-key",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
Schema:
NotificationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"notification": {
"active": true,
"createdAt": "2026-03-27T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"port.arrival",
"position.update"
],
"geofence": {
"latBottom": 51.8,
"latTop": 52.1,
"lonLeft": 3.5,
"lonRight": 4.5
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"imos": [
9321483,
9472440
],
"mmsis": [
477045900
],
"name": "My fleet alerts",
"speedThresholdKnots": 0.5,
"updatedAt": "2026-03-27T12:00:00Z",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
}
/v1/notifications/{id}
v1
🔒 Auth Required
Delete notification
Delete a notification configuration and stop all event delivery
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path | Notification ID |
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
Schema:
InternalServerErrorResponse
/v1/notifications/{id}
v1
🔒 Auth Required
Get notification
Get a notification configuration by ID
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path |
Notification ID
Example:
550e8400-e29b-41d4-a716-446655440000 |
Schema:
NotificationResponse
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
Schema:
InternalServerErrorResponse
{
"notification": {
"active": true,
"createdAt": "2026-03-27T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"port.arrival",
"position.update"
],
"geofence": {
"latBottom": 51.8,
"latTop": 52.1,
"lonLeft": 3.5,
"lonRight": 4.5
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"imos": [
9321483,
9472440
],
"mmsis": [
477045900
],
"name": "My fleet alerts",
"speedThresholdKnots": 0.5,
"updatedAt": "2026-03-27T12:00:00Z",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
}
/v1/notifications/{id}
v1
🔒 Auth Required
Update notification
Update a notification configuration. Only provided fields are changed.
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path | Notification ID |
body
*
|
UpdateNotificationRequest
|
body | Fields to update |
Request Body (UpdateNotificationRequest)
{
"active": true,
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"port.arrival",
"position.update"
],
"geofence": {
"latBottom": 51.8,
"latTop": 52.1,
"lonLeft": 3.5,
"lonRight": 4.5
},
"imos": [
9321483,
9472440
],
"mmsis": [
477045900
],
"name": "Updated fleet name",
"speedThresholdKnots": 0.5,
"webhookSecret": "my-secret-key",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
Schema:
NotificationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
Schema:
InternalServerErrorResponse
{
"notification": {
"active": true,
"createdAt": "2026-03-27T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"port.arrival",
"position.update"
],
"geofence": {
"latBottom": 51.8,
"latTop": 52.1,
"lonLeft": 3.5,
"lonRight": 4.5
},
"id": "550e8400-e29b-41d4-a716-446655440000",
"imos": [
9321483,
9472440
],
"mmsis": [
477045900
],
"name": "My fleet alerts",
"speedThresholdKnots": 0.5,
"updatedAt": "2026-03-27T12:00:00Z",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
}
/v1/notifications/{id}/test
v1
🔒 Auth Required
Test notification
Send a test event to verify webhook delivery and see the event payload format. The test event is delivered through all configured channels (webhook and/or WebSocket).
| Name | Type | In | Description |
|---|---|---|---|
id
*
|
string | path | Notification ID |
Schema:
TestResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
Schema:
InternalServerErrorResponse
{
"delivered_to": [
"webhook",
"websocket"
],
"payload": {
"event": {
"data": {},
"detectedAt": "2026-03-27T12:05:00Z",
"id": "94ff8b0d-08d8-466c-b37a-c024117b8880",
"notificationId": "550e8400-e29b-41d4-a716-446655440000",
"notificationName": "europe_registration",
"timestamp": "2026-03-27T12:00:00Z",
"type": "position.position_changed",
"vessel": {}
},
"object": "event"
},
"results": [
{
"channel": "webhook",
"durationMs": 127,
"error": "connection refused",
"statusCode": 200,
"success": true
}
]
}
AdvancedNotifications
more in v1/v1/notifications/advanced
v1
🔒 Auth Required
List advanced notifications
List all advanced notifications for the authenticated user.
No parameters
Schema:
AdvancedNotificationListResponse
Schema:
AuthenticationErrorResponse
Schema:
InternalServerErrorResponse
{
"notifications": [
{
"active": true,
"createdAt": "2026-04-19T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"position.geofence_enter",
"position.geofence_exit"
],
"filterGroups": [
{}
],
"hysteresisMeters": 50,
"mode": "any_vessel",
"name": "europe_registration",
"polygon": {
"coordinates": [
[
0
]
]
},
"prefillCompletedAt": "string",
"prefillError": "string",
"prefillStartedAt": "string",
"prefillStatus": "ready",
"updatedAt": "2026-04-19T12:00:00Z",
"vessels": [
{}
],
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
]
}
/v1/notifications/advanced
v1
🔒 Auth Required
Create advanced notification
Create an advanced notification with polygon geofence, attribute filters, and optional uncapped vessel matching. Requires the Pro subscription plan. The notification is created with prefillStatus "pending" and starts delivering events once prefill completes (prefillStatus "ready"); poll GET /notifications/advanced/{name} to track it, or pass skipPrefill=true to start immediately and receive an enter event for every currently-matching vessel. Limits: 50 advanced notifications per account, polygon ring of 4-5000 [lon,lat] points, vessel_list mode up to 10000 vessels (each entry requires an MMSI), up to 20 filter groups of 20 predicates.
| Name | Type | In | Description |
|---|---|---|---|
body
*
|
CreateAdvancedNotificationRequest
|
body | Advanced notification configuration |
Request Body (CreateAdvancedNotificationRequest)
{
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"position.geofence_enter",
"position.geofence_exit"
],
"filterGroups": [
{
"predicates": [
{}
]
}
],
"hysteresisMeters": 50,
"mode": "any_vessel",
"name": "europe_registration",
"polygon": {
"coordinates": [
[
0
]
]
},
"skipPrefill": false,
"vessels": [
{
"imo": 9321483,
"mmsi": 477045900
}
],
"webhookSecret": "my-secret-key",
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
Schema:
AdvancedNotificationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
ConflictErrorResponse
Schema:
RateLimitErrorResponse
Schema:
InternalServerErrorResponse
{
"notification": {
"active": true,
"createdAt": "2026-04-19T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"position.geofence_enter",
"position.geofence_exit"
],
"filterGroups": [
{
"predicates": [
{}
]
}
],
"hysteresisMeters": 50,
"mode": "any_vessel",
"name": "europe_registration",
"polygon": {
"coordinates": [
[
0
]
]
},
"prefillCompletedAt": "string",
"prefillError": "string",
"prefillStartedAt": "string",
"prefillStatus": "ready",
"updatedAt": "2026-04-19T12:00:00Z",
"vessels": [
{
"imo": 9321483,
"mmsi": 477045900
}
],
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
}
/v1/notifications/advanced/{name}
v1
🔒 Auth Required
Delete advanced notification
Delete an advanced notification and stop all event delivery. State and allowlist are removed via cascade.
| Name | Type | In | Description |
|---|---|---|---|
name
*
|
string | path | Notification name |
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
/v1/notifications/advanced/{name}
v1
🔒 Auth Required
Get advanced notification
Get an advanced notification by name.
| Name | Type | In | Description |
|---|---|---|---|
name
*
|
string | path |
Notification name
Example:
europe_registration |
Schema:
AdvancedNotificationResponse
Schema:
AuthenticationErrorResponse
Schema:
NotFoundErrorResponse
{
"notification": {
"active": true,
"createdAt": "2026-04-19T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"position.geofence_enter",
"position.geofence_exit"
],
"filterGroups": [
{
"predicates": [
{}
]
}
],
"hysteresisMeters": 50,
"mode": "any_vessel",
"name": "europe_registration",
"polygon": {
"coordinates": [
[
0
]
]
},
"prefillCompletedAt": "string",
"prefillError": "string",
"prefillStartedAt": "string",
"prefillStatus": "ready",
"updatedAt": "2026-04-19T12:00:00Z",
"vessels": [
{
"imo": 9321483,
"mmsi": 477045900
}
],
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
}
/v1/notifications/advanced/{name}
v1
🔒 Auth Required
Update advanced notification
Update an advanced notification. Only provided fields are changed. Name and mode cannot be changed. Changing the polygon or filters (or reactivating an inactive notification) resets prefillStatus to "pending": event delivery pauses until prefill completes again.
| Name | Type | In | Description |
|---|---|---|---|
name
*
|
string | path | Notification name |
body
*
|
UpdateAdvancedNotificationRequest
|
body | Fields to update |
Request Body (UpdateAdvancedNotificationRequest)
{
"active": false,
"etaShiftThresholdMinutes": 0,
"eventTypes": [
"string"
],
"filterGroups": [
{
"predicates": [
{}
]
}
],
"hysteresisMeters": 0,
"polygon": {
"coordinates": [
[
0
]
]
},
"vessels": [
{
"imo": 9321483,
"mmsi": 477045900
}
],
"webhookSecret": "string",
"webhookUrl": "string",
"websocket": false
}
Schema:
AdvancedNotificationResponse
Schema:
BadRequestErrorResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
{
"notification": {
"active": true,
"createdAt": "2026-04-19T12:00:00Z",
"etaShiftThresholdMinutes": 120,
"eventTypes": [
"position.geofence_enter",
"position.geofence_exit"
],
"filterGroups": [
{
"predicates": [
{}
]
}
],
"hysteresisMeters": 50,
"mode": "any_vessel",
"name": "europe_registration",
"polygon": {
"coordinates": [
[
0
]
]
},
"prefillCompletedAt": "string",
"prefillError": "string",
"prefillStartedAt": "string",
"prefillStatus": "ready",
"updatedAt": "2026-04-19T12:00:00Z",
"vessels": [
{
"imo": 9321483,
"mmsi": 477045900
}
],
"webhookUrl": "https://example.com/webhook",
"websocket": false
}
}
/v1/notifications/advanced/{name}/test
v1
🔒 Auth Required
Test advanced notification
Send a test event to verify webhook + websocket delivery for an advanced notification. The notification must be active.
| Name | Type | In | Description |
|---|---|---|---|
name
*
|
string | path | Notification name |
Schema:
TestResponse
Schema:
AuthenticationErrorResponse
Schema:
ForbiddenErrorResponse
Schema:
NotFoundErrorResponse
Schema:
ConflictErrorResponse
{
"delivered_to": [
"webhook",
"websocket"
],
"payload": {
"event": {
"data": {},
"detectedAt": "2026-03-27T12:05:00Z",
"id": "94ff8b0d-08d8-466c-b37a-c024117b8880",
"notificationId": "550e8400-e29b-41d4-a716-446655440000",
"notificationName": "europe_registration",
"timestamp": "2026-03-27T12:00:00Z",
"type": "position.position_changed",
"vessel": {}
},
"object": "event"
},
"results": [
{
"channel": "webhook",
"durationMs": 127,
"error": "connection refused",
"statusCode": 200,
"success": true
}
]
}