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 v1

Retrieve vessel information including positions, static data, and estimated time of arrival by MMSI, IMO, name, or location

GET /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
200 OK

Schema: VesselsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  ]
}
GET /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
200 OK

Schema: VesselsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  ]
}
GET /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, ENI, callsign, and vessel name. Matches a vessel if any of those identifiers matches, so one value can return more than one vessel; the _meta.matchedOn field on the response names the fields that matched. An ENI matches with or without its leading zeros. 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.eni string query European Number of Identification, the inland waterway equivalent of an IMO. Leading zeros optional: 4606770 and 04606770 both match.
Example: 04606770
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
200 OK

Schema: FindVesselsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "matchedOn": {},
    "query": "4606770"
  },
  "nextToken": "string",
  "vessels": [
    {
      "breadth": 59,
      "breadth_unit": "m",
      "call_sign": "H3RC",
      "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",
      "mmsi": 477045900,
      "name": "EVER GIVEN",
      "name_ais": "EVER GIVEN",
      "operating_status": "Active",
      "speed_calculated_avg": 12.4,
      "speed_observed_max": 22.1,
      "summer_draught": 16.5,
      "teu": 23992,
      "vessel_subtype": "Inland cargo",
      "vessel_type": "Container Ship",
      "year_built": 2018
    }
  ]
}
GET /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: mmsi
Enum: mmsi, imo
200 OK

Schema: VesselResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "requestedIdType": "string",
    "resolvedId": 0,
    "resolvedIdType": "string",
    "suggestedIdType": "string"
  },
  "vessel": {
    "breadth": 59,
    "breadth_unit": "m",
    "call_sign": "H3RC",
    "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",
    "mmsi": 477045900,
    "name": "EVER GIVEN",
    "name_ais": "EVER GIVEN",
    "operating_status": "Active",
    "speed_calculated_avg": 12.4,
    "speed_observed_max": 22.1,
    "summer_draught": 16.5,
    "teu": 23992,
    "vessel_subtype": "Inland cargo",
    "vessel_type": "Container Ship",
    "year_built": 2018
  }
}
GET /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: mmsi
Enum: mmsi, imo
200 OK

Schema: VesselETAResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
  }
}
GET /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: mmsi
Enum: mmsi, imo
filter.sat boolean query Enable satellite AIS fallback (default: false)
Example: false
200 OK

Schema: VesselPositionResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

402 Insufficient satellite credits and no stored position to fall back on

Schema: PaymentRequiredErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
  }
}
GET /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: mmsi
Enum: 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
200 OK

Schema: VesselPositionsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  ]
}

Regulatory Records

more in v1

EU MRV-verified emissions and energy-efficiency metrics, plus marine casualty and incident records by vessel

GET /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
200 OK

Schema: VesselEmissionsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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",
      "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"
}
GET /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: imo
Enum: 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
200 OK

Schema: MarineCasualtiesResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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: imo
Enum: 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
200 OK

Schema: VesselEmissionsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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",
      "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"
}

Ports

more in v1

Search world port index data by location, name, or geographic area

GET /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
200 OK

Schema: PortsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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
    }
  ]
}
GET /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
200 OK

Schema: PortsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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
    }
  ]
}
GET /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
200 OK

Schema: PortResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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
  }
}
GET /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
200 OK

Schema: PortInboundResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  ]
}
GET /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
200 OK

Schema: FindPortsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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 v1

Access port call information including vessel arrivals, departures, and current port activity

GET /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
200 OK

Schema: PortEventsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "requestedIdType": "string",
    "resolvedId": 0,
    "resolvedIdType": "string",
    "suggestedIdType": "string"
  },
  "nextToken": "string",
  "portEvents": [
    {
      "event": "Arrival",
      "port": {},
      "timestamp": "string",
      "vessel": {}
    }
  ]
}
GET /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
200 OK

Schema: PortEventsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "requestedIdType": "string",
    "resolvedId": 0,
    "resolvedIdType": "string",
    "suggestedIdType": "string"
  },
  "nextToken": "string",
  "portEvents": [
    {
      "event": "Arrival",
      "port": {},
      "timestamp": "string",
      "vessel": {}
    }
  ]
}
GET /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
200 OK

Schema: PortEventsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "requestedIdType": "string",
    "resolvedId": 0,
    "resolvedIdType": "string",
    "suggestedIdType": "string"
  },
  "nextToken": "string",
  "portEvents": [
    {
      "event": "Arrival",
      "port": {},
      "timestamp": "string",
      "vessel": {}
    }
  ]
}
GET /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: all
Enum: arrival, departure, all
filter.sortOrder string query Sort order by timestamp
Default: desc
Enum: 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
200 OK

Schema: PortEventsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "requestedIdType": "string",
    "resolvedId": 0,
    "resolvedIdType": "string",
    "suggestedIdType": "string"
  },
  "nextToken": "string",
  "portEvents": [
    {
      "event": "Arrival",
      "port": {},
      "timestamp": "string",
      "vessel": {}
    }
  ]
}
GET /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
200 OK

Schema: PortEventResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  }
}
GET /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
200 OK

Schema: PortEventsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse 

{
  "_meta": {
    "requestedIdType": "string",
    "resolvedId": 0,
    "resolvedIdType": "string",
    "suggestedIdType": "string"
  },
  "nextToken": "string",
  "portEvents": [
    {
      "event": "Arrival",
      "port": {},
      "timestamp": "string",
      "vessel": {}
    }
  ]
}

Navigation Infrastructure

more in v1

Locate maritime navigation aids and infrastructure including DGPS stations, light aids, MODUs, and radio beacons by geographic coordinates or name

GET /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
200 OK

Schema: DGPSStationsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: DGPSStationsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: LightAidsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: LightAidsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: MODUsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: MODUsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: RadioBeaconsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  ]
}
GET /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
200 OK

Schema: RadioBeaconsWithinLocationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
    }
  ]
}
GET /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
200 OK

Schema: FindDGPSStationsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: FindLightAidsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: FindMODUsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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"
}
GET /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
200 OK

Schema: FindRadioBeaconsResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 API key temporarily suspended for sustained quota abuse; see Retry-After header

Schema: ForbiddenErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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 v1

Real-time event streaming via WebSocket. Connect to receive events as they occur instead of via webhook callbacks.

GET /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
101 Switching Protocols - WebSocket connection established
400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

GET /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
101 Switching Protocols - WebSocket connection established
400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 Subscription plan does not include advanced notifications (Pro required)

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

409 code notification_inactive (re-enable before connecting) or prefill_pending (retry shortly; Retry-After header set)

Schema: ConflictErrorResponse

Notifications

more in v1

Create and manage vessel notification configurations. Each notification watches a set of vessels and delivers events via webhook and/or WebSocket.

GET /v1/notifications v1 🔒 Auth Required

List notifications

List all notification configurations for the authenticated user

No parameters

200 OK

Schema: NotificationListResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

500 Internal Server Error

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
    }
  ]
}
POST /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
}
201 Created

Schema: NotificationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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
  }
}
DELETE /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
204 No Content
401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

500 Internal Server Error

Schema: InternalServerErrorResponse

GET /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
200 OK

Schema: NotificationResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

500 Internal Server Error

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
  }
}
PUT /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
}
200 OK

Schema: NotificationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

500 Internal Server Error

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
  }
}
POST /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
200 OK

Schema: TestResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

500 Internal Server Error

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
GET /v1/notifications/advanced v1 🔒 Auth Required

List advanced notifications

List all advanced notifications for the authenticated user.

No parameters

200 OK

Schema: AdvancedNotificationListResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

500 Internal Server Error

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
    }
  ]
}
POST /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
}
201 Created

Schema: AdvancedNotificationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 Subscription plan does not include advanced notifications (Pro required)

Schema: ForbiddenErrorResponse

409 An advanced notification with this name already exists

Schema: ConflictErrorResponse

429 Too Many Requests

Schema: RateLimitErrorResponse

500 Internal Server Error

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
  }
}
DELETE /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
204 No Content
401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

GET /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
200 OK

Schema: AdvancedNotificationResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

404 Not Found

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
  }
}
PUT /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
}
200 OK

Schema: AdvancedNotificationResponse

400 Bad Request

Schema: BadRequestErrorResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 Subscription plan does not include advanced notifications (Pro required)

Schema: ForbiddenErrorResponse

404 Not Found

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
  }
}
POST /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
200 OK

Schema: TestResponse

401 Unauthorized

Schema: AuthenticationErrorResponse

403 Subscription plan does not include advanced notifications (Pro required)

Schema: ForbiddenErrorResponse

404 Not Found

Schema: NotFoundErrorResponse

409 Notification is inactive (code notification_inactive)

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
    }
  ]
}