{ "schemes": [ "https" ], "swagger": "2.0", "info": { "description": "Maritime vessel tracking and marine navigation data API providing recent terrestrial AIS positions, 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). The heavy endpoints (ETA lookup by IMO for a vessel absent from the registry, port inbound lists) can return 503 with Retry-After: 5 when the server is at its cap for such queries; a 503 is not counted against quota, retry after the delay. Unknown query parameters are rejected with 400.", "title": "Vessel Tracking API", "contact": {}, "version": "1.0" }, "host": "api.vesselapi.com", "paths": { "/v1/emissions": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves emissions data with optional filtering by reporting period", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Regulatory Records" ], "summary": "List emissions data", "parameters": [ { "type": "integer", "example": 2024, "description": "Reporting year filter (e.g. 2024)", "name": "filter.period", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Pagination token for retrieving the next page of results", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselEmissionsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/dgps/bounding-box": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Dgps stations within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get DGPS Stations within a bounding box", "parameters": [ { "type": "number", "example": 7, "description": "Longitude of the left (western) edge of the bounding box", "name": "filter.lonLeft", "in": "query", "required": true }, { "type": "number", "example": 9, "description": "Longitude of the right (eastern) edge of the bounding box", "name": "filter.lonRight", "in": "query", "required": true }, { "type": "number", "example": 55, "description": "Latitude of the bottom (southern) edge of the bounding box", "name": "filter.latBottom", "in": "query", "required": true }, { "type": "number", "example": 56, "description": "Latitude of the top (northern) edge of the bounding box", "name": "filter.latTop", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/DGPSStationsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/dgps/radius": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Dgps stations within a specified radius of a given point", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get DGPS Stations within a radius", "parameters": [ { "type": "number", "example": 8.084, "description": "Longitude of the center point", "name": "filter.longitude", "in": "query", "required": true }, { "type": "number", "example": 55.558, "description": "Latitude of the center point", "name": "filter.latitude", "in": "query", "required": true }, { "type": "number", "example": 10000, "description": "Search radius in meters (max 100,000 = 100 km)", "name": "filter.radius", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/DGPSStationsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/lightaids/bounding-box": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Light Aids to Navigation within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get Light Aids to Navigation within a bounding box", "parameters": [ { "type": "number", "example": 4, "description": "Longitude of the left (western) edge of the bounding box", "name": "filter.lonLeft", "in": "query", "required": true }, { "type": "number", "example": 5, "description": "Longitude of the right (eastern) edge of the bounding box", "name": "filter.lonRight", "in": "query", "required": true }, { "type": "number", "example": 51, "description": "Latitude of the bottom (southern) edge of the bounding box", "name": "filter.latBottom", "in": "query", "required": true }, { "type": "number", "example": 52, "description": "Latitude of the top (northern) edge of the bounding box", "name": "filter.latTop", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/LightAidsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/lightaids/radius": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Light Aids to Navigation within a specified radius of a given point", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get Light Aids to Navigation within a radius", "parameters": [ { "type": "number", "example": 4.5, "description": "Longitude of the center point", "name": "filter.longitude", "in": "query", "required": true }, { "type": "number", "example": 51.5, "description": "Latitude of the center point", "name": "filter.latitude", "in": "query", "required": true }, { "type": "number", "example": 100000, "description": "Search radius in meters (max 100,000 = 100 km)", "name": "filter.radius", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/LightAidsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/modu/bounding-box": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Mobile Offshore Drilling Units within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get Mobile Offshore Drilling Units within a bounding box", "parameters": [ { "type": "number", "example": -89, "description": "Longitude of the left (western) edge of the bounding box", "name": "filter.lonLeft", "in": "query", "required": true }, { "type": "number", "example": -88, "description": "Longitude of the right (eastern) edge of the bounding box", "name": "filter.lonRight", "in": "query", "required": true }, { "type": "number", "example": 28, "description": "Latitude of the bottom (southern) edge of the bounding box", "name": "filter.latBottom", "in": "query", "required": true }, { "type": "number", "example": 29, "description": "Latitude of the top (northern) edge of the bounding box", "name": "filter.latTop", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MODUsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/modu/radius": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Mobile Offshore Drilling Units within a specified radius of a given point", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get Mobile Offshore Drilling Units within a radius", "parameters": [ { "type": "number", "example": -88.5, "description": "Longitude of the center point", "name": "filter.longitude", "in": "query", "required": true }, { "type": "number", "example": 28.2, "description": "Latitude of the center point", "name": "filter.latitude", "in": "query", "required": true }, { "type": "number", "example": 50000, "description": "Search radius in meters (max 100,000 = 100 km)", "name": "filter.radius", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MODUsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/ports/bounding-box": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Ports within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Ports" ], "summary": "Get Ports within a bounding box", "parameters": [ { "type": "number", "example": 4, "description": "Longitude of the left (western) edge of the bounding box", "name": "filter.lonLeft", "in": "query", "required": true }, { "type": "number", "example": 5, "description": "Longitude of the right (eastern) edge of the bounding box", "name": "filter.lonRight", "in": "query", "required": true }, { "type": "number", "example": 51, "description": "Latitude of the bottom (southern) edge of the bounding box", "name": "filter.latBottom", "in": "query", "required": true }, { "type": "number", "example": 52, "description": "Latitude of the top (northern) edge of the bounding box", "name": "filter.latTop", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/ports/radius": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Ports within a specified radius of a given point", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Ports" ], "summary": "Get Ports within a radius", "parameters": [ { "type": "number", "example": 4.5, "description": "Longitude of the center point", "name": "filter.longitude", "in": "query", "required": true }, { "type": "number", "example": 51.5, "description": "Latitude of the center point", "name": "filter.latitude", "in": "query", "required": true }, { "type": "number", "example": 100000, "description": "Search radius in meters (max 100,000 = 100 km)", "name": "filter.radius", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/radiobeacons/bounding-box": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Radio Beacons within a specified bounding box. Max span: |dLat| + |dLon| ≤ 4 degrees", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get Radio Beacons within a bounding box", "parameters": [ { "type": "number", "example": -1, "description": "Longitude of the left (western) edge of the bounding box", "name": "filter.lonLeft", "in": "query", "required": true }, { "type": "number", "example": 1, "description": "Longitude of the right (eastern) edge of the bounding box", "name": "filter.lonRight", "in": "query", "required": true }, { "type": "number", "example": 50, "description": "Latitude of the bottom (southern) edge of the bounding box", "name": "filter.latBottom", "in": "query", "required": true }, { "type": "number", "example": 51, "description": "Latitude of the top (northern) edge of the bounding box", "name": "filter.latTop", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/RadioBeaconsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/radiobeacons/radius": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves Radio Beacons within a specified radius of a given point", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Get Radio Beacons within a radius", "parameters": [ { "type": "number", "example": -0.1, "description": "Longitude of the center point", "name": "filter.longitude", "in": "query", "required": true }, { "type": "number", "example": 50.8, "description": "Latitude of the center point", "name": "filter.latitude", "in": "query", "required": true }, { "type": "number", "example": 100000, "description": "Search radius in meters (max 100,000 = 100 km)", "name": "filter.radius", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/RadioBeaconsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/vessels/bounding-box": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "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.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Get vessels within a bounding box", "parameters": [ { "type": "number", "example": 4.8, "description": "Longitude of the left (western) edge of the bounding box", "name": "filter.lonLeft", "in": "query", "required": true }, { "type": "number", "example": 5, "description": "Longitude of the right (eastern) edge of the bounding box", "name": "filter.lonRight", "in": "query", "required": true }, { "type": "number", "example": 51.5, "description": "Latitude of the bottom (southern) edge of the bounding box", "name": "filter.latBottom", "in": "query", "required": true }, { "type": "number", "example": 52, "description": "Latitude of the top (northern) edge of the bounding box", "name": "filter.latTop", "in": "query", "required": true }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago). Max window 4 hours.", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time). Max window 4 hours.", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/location/vessels/radius": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "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.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Get vessels within a radius", "parameters": [ { "type": "number", "example": 4.5, "description": "Longitude of the center point", "name": "filter.longitude", "in": "query", "required": true }, { "type": "number", "example": 51.5, "description": "Latitude of the center point", "name": "filter.latitude", "in": "query", "required": true }, { "type": "number", "example": 10000, "description": "Search radius in meters (max 100,000 = 100 km)", "name": "filter.radius", "in": "query", "required": true }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago). Max window 4 hours.", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time). Max window 4 hours.", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselsWithinLocationResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/port/{unlocode}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves port details by its UN/LOCODE (e.g., NLRTM for Rotterdam, SGSIN for Singapore)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Ports" ], "summary": "Get Port by UNLOCODE", "parameters": [ { "type": "string", "example": "NLRTM", "description": "UN/LOCODE of the port", "name": "unlocode", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/port/{unlocode}/inbound": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves vessels heading to a specific port within an ETA window", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Ports" ], "summary": "Get Inbound Vessels for Port", "parameters": [ { "type": "string", "example": "DEEME", "description": "UN/LOCODE of the destination port", "name": "unlocode", "in": "path", "required": true }, { "type": "string", "description": "Start of ETA arrival window in RFC3339 format (defaults to now)", "name": "filter.etaFrom", "in": "query" }, { "type": "string", "description": "End of ETA arrival window in RFC3339 format (defaults to 72 hours ahead)", "name": "filter.etaTo", "in": "query" }, { "type": "string", "description": "Report freshness start (defaults to 24 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "Report freshness end (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortInboundResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } }, "503": { "description": "At capacity for heavy queries (inbound lists); not counted against quota, see Retry-After header", "schema": { "$ref": "#/definitions/ServiceUnavailableErrorResponse" } } } } }, "/v1/portevents": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get Port Events, such as Arrivals and Departures, in a time range with optional filters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Port Events" ], "summary": "Get Port Events in a time range", "parameters": [ { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "string", "description": "Filter by port country (case-insensitive)", "name": "filter.country", "in": "query" }, { "type": "string", "example": "SGSIN", "description": "Filter by port UN/LOCODE", "name": "filter.unlocode", "in": "query" }, { "enum": [ "arrival", "departure", "all" ], "type": "string", "description": "Filter by event type", "name": "filter.eventType", "in": "query" }, { "type": "string", "description": "Filter by vessel name (full-text search)", "name": "filter.vesselName", "in": "query" }, { "type": "string", "description": "Filter by port name (full-text search)", "name": "filter.portName", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortEventsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/portevents/port/{unlocode}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get Port Events, such as Arrivals and Departures by supplying the port UN/LOCODE (e.g., NLRTM for Rotterdam, SGSIN for Singapore)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Port Events" ], "summary": "Get Port Events by port UNLOCODE", "parameters": [ { "type": "string", "example": "NLRTM", "description": "UN/LOCODE of the port", "name": "unlocode", "in": "path", "required": true }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortEventsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/portevents/ports": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get Port Events, such as Arrivals and Departures by supplying the port name", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Port Events" ], "summary": "Get Port Events by port name", "parameters": [ { "type": "string", "example": "Rotterdam", "description": "Port name", "name": "filter.portName", "in": "query", "required": true }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortEventsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/portevents/vessel/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get all port events (arrivals and departures) for a vessel identified by MMSI or IMO, with optional filtering by event type and time range", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Port Events" ], "summary": "Get Port Events by Vessel ID", "parameters": [ { "type": "string", "example": "232003239", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "description": "Identifier type (mmsi or imo)", "name": "filter.idType", "in": "query", "required": true }, { "enum": [ "arrival", "departure", "all" ], "type": "string", "default": "all", "description": "Filter by event type", "name": "filter.eventType", "in": "query" }, { "enum": [ "asc", "desc" ], "type": "string", "default": "desc", "description": "Sort order by timestamp", "name": "filter.sortOrder", "in": "query" }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortEventsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/portevents/vessel/{id}/last": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get the most recent port event (arrival or departure) for a vessel identified by MMSI or IMO", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Port Events" ], "summary": "Get Last Port Event by ID", "parameters": [ { "type": "string", "example": "232003239", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "description": "Identifier type (mmsi or imo)", "name": "filter.idType", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortEventResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/portevents/vessels": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Get Port Events by vessel name", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Port Events" ], "summary": "Get Port Events by vessel name", "parameters": [ { "type": "string", "example": "strangford 2", "description": "Vessel name", "name": "filter.vesselName", "in": "query", "required": true }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PortEventsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/search/dgps": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list of DGPS stations for the given query parameters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Search for DGPS Stations", "parameters": [ { "type": "string", "example": "Hammer Odde", "description": "Name of the DGPS station", "name": "filter.name", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FindDGPSStationsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/search/lightaids": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list of Light Aids to Navigation for the given query parameters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Search for Light Aids to Navigation", "parameters": [ { "type": "string", "example": "Creach", "description": "Name of the Light Aid", "name": "filter.name", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FindLightAidsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/search/modus": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list of MODUs for the given query parameters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Search for MODUs", "parameters": [ { "type": "string", "example": "ABAN", "description": "Name of the MODU", "name": "filter.name", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FindMODUsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/search/ports": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list of ports matching the given filters. At least one filter parameter is required.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Ports" ], "summary": "Search for Ports", "parameters": [ { "type": "string", "example": "Rotterdam", "description": "Name of the port", "name": "filter.name", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "multi", "example": "NL", "description": "ISO 2-letter country code(s) or country name(s). Repeat the parameter to match multiple.", "name": "filter.country", "in": "query" }, { "type": "array", "items": { "enum": [ "Port" ], "type": "string" }, "collectionFormat": "multi", "example": "Port", "description": "Port type classification(s) (case-insensitive). Repeat the parameter to match multiple. Note: not all ports have a type assigned.", "name": "filter.type", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "multi", "example": "Large", "description": "Port size classification(s). Repeat the parameter to match multiple.", "name": "filter.size", "in": "query" }, { "type": "string", "description": "Geographic region name (partial match)", "name": "filter.region", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "multi", "example": "Large", "description": "Harbor size classification(s). Repeat the parameter to match multiple.", "name": "filter.harborSize", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "multi", "description": "Primary harbor use(s). Repeat the parameter to match multiple.", "name": "filter.harborUse", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FindPortsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/search/radiobeacons": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list of Radio Beacons for the given query parameters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Navigation Infrastructure" ], "summary": "Search for Radio Beacons", "parameters": [ { "type": "string", "example": "Brighton", "description": "Name of the Radio Beacon", "name": "filter.name", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FindRadioBeaconsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/search/vessels": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves a list of vessels matching the given filters. At least one filter parameter (or the unified `q` parameter) is required.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Search for Vessels", "parameters": [ { "type": "string", "example": "EVER GIVEN", "description": "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.", "name": "q", "in": "query" }, { "type": "string", "example": "EVER GIVEN", "description": "Name of the vessel", "name": "filter.name", "in": "query" }, { "type": "string", "example": "H3RC", "description": "Radio callsign of the vessel", "name": "filter.callsign", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "multi", "example": "PA", "description": "ISO 2-letter country code(s) of the flag state. Repeat the parameter to match multiple.", "name": "filter.flag", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "multi", "example": "Cargo A", "description": "Vessel type classification(s) (case-insensitive). Repeat the parameter to match multiple.", "name": "filter.vesselType", "in": "query" }, { "type": "integer", "example": 353136000, "description": "MMSI number", "name": "filter.mmsi", "in": "query" }, { "type": "integer", "example": 9811000, "description": "IMO number", "name": "filter.imo", "in": "query" }, { "type": "integer", "example": 2010, "description": "Minimum year built", "name": "filter.yearBuiltMin", "in": "query" }, { "type": "integer", "example": 2020, "description": "Maximum year built", "name": "filter.yearBuiltMax", "in": "query" }, { "type": "string", "description": "European Number of Identification, the inland waterway equivalent of an IMO. Leading zeros optional: 4606770 and 04606770 both match.", "name": "filter.eni", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Token for next page", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FindVesselsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/vessel/{id}": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves static vessel data including name, type, dimensions, and registration information for a vessel identified by its MMSI or IMO number", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Get vessel information by MMSI or IMO", "parameters": [ { "type": "string", "example": "232003239", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "example": "mmsi", "description": "Identifier type: 'mmsi' or 'imo'", "name": "filter.idType", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/vessel/{id}/casualties": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves marine casualty records involving the specified vessel", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Regulatory Records" ], "summary": "Get marine casualties involving a vessel", "parameters": [ { "type": "string", "example": "9074729", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "example": "imo", "description": "Identifier type: 'mmsi' or 'imo'", "name": "filter.idType", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Pagination token for retrieving the next page of results", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MarineCasualtiesResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/vessel/{id}/emissions": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves emissions reports for the specified vessel including CO2 emissions, fuel consumption, and efficiency metrics", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Regulatory Records" ], "summary": "Get emissions data for a vessel", "parameters": [ { "type": "string", "example": "1045356", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "example": "imo", "description": "Identifier type: 'mmsi' or 'imo'", "name": "filter.idType", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Pagination token for retrieving the next page of results", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselEmissionsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/vessel/{id}/eta": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves the most recent Estimated Time of Arrival (ETA) reported by the vessel", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Get vessel latest ETA", "parameters": [ { "type": "string", "example": "232003239", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "example": "mmsi", "description": "Identifier type: 'mmsi' or 'imo'", "name": "filter.idType", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselETAResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } }, "503": { "description": "At capacity for heavy queries (ETA lookup by IMO for a vessel absent from the registry); not counted against quota, see Retry-After header", "schema": { "$ref": "#/definitions/ServiceUnavailableErrorResponse" } } } } }, "/v1/vessel/{id}/position": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "Retrieves the most recent AIS position report for a vessel, including coordinates, vessel identifiers, and timestamps. The satellite fallback (filter.sat) is deprecated: it is withdrawn in its current form, and from the date in the Sunset header the parameter is accepted and ignored. The response also includes the vessel's particulars (vessel), the latest destination and ETA it reported (vesselEta), and positionCheck, which compares the position with the vessel's previous position report: time and distance since then, implied speed and course, and whether the identifiers match.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Get last known vessel position", "parameters": [ { "type": "string", "example": "232003239", "description": "MMSI or IMO number", "name": "id", "in": "path", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "example": "mmsi", "description": "Identifier type: 'mmsi' or 'imo'", "name": "filter.idType", "in": "query", "required": true }, { "type": "boolean", "example": false, "x-deprecated": "true", "description": "Deprecated. The satellite fallback is withdrawn in its current form. Requests with filter.sat=true keep working for existing credit holders until the cutoff date and carry Deprecation and Sunset headers (the Sunset header gives the date). From the cutoff date the parameter is accepted and ignored, the response carries a Warning header, and no credit is charged. Until then: enable satellite AIS fallback (default: false)", "name": "filter.sat", "in": "query" }, { "type": "integer", "example": 480, "x-deprecated": "true", "description": "Deprecated with filter.sat; accepted and ignored from the cutoff date. Until then, with filter.sat=true: how old a satellite-lookup fix may be and still be returned, 60-4800 minutes (default: 180)", "name": "filter.satLookbackMinutes", "in": "query" }, { "type": "integer", "example": 15, "x-deprecated": "true", "description": "Deprecated with filter.sat; accepted and ignored from the cutoff date. Until then, with filter.sat=true: how old a stored position may be before a satellite lookup is made, 15-4800 minutes (default: 60). Paid plans only", "name": "filter.satMaxAgeMinutes", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselPositionResponse" }, "headers": { "Deprecation": { "type": "string", "description": "Present when filter.sat or its window parameters are sent, from the notice date until the cutoff date: '@' followed by the notice date as Unix seconds (RFC 9745)" }, "Link": { "type": "string", "description": "Present with Deprecation: the documentation of the deprecation, with rel=deprecation" }, "Sunset": { "type": "string", "description": "Present with Deprecation: the cutoff date of the satellite fallback as an HTTP-date (RFC 8594)" }, "Warning": { "type": "string", "description": "Present from the cutoff date when filter.sat or its window parameters are sent: 299 warning that the satellite fallback was withdrawn and filter.sat is ignored" }, "X-Data-Source": { "type": "string", "description": "Deprecated with filter.sat. Data source: 'satellite' or 'terrestrial' (only present when filter.sat is sent). From the cutoff date always 'terrestrial'" }, "X-Satellite-Credit-Charged": { "type": "string", "description": "Deprecated with filter.sat. 'true' if a satellite credit was deducted. Never sent from the cutoff date" }, "X-Satellite-Credits-Remaining": { "type": "string", "description": "Deprecated with filter.sat. Satellite credit balance after this request; present on every filter.sat=true response until the cutoff date" }, "X-Satellite-Lookback-Minutes": { "type": "string", "description": "Deprecated with filter.sat. Satellite lookback applied to this request, in minutes; present on every filter.sat=true response until the cutoff date" }, "X-Satellite-Max-Age-Minutes": { "type": "string", "description": "Deprecated with filter.sat. Stored-position age limit applied to this request, in minutes; present on every filter.sat=true response until the cutoff date" }, "X-Satellite-Status": { "type": "string", "description": "Deprecated with filter.sat. 'insufficient_credits' when filter.sat=true but the balance was empty, so the satellite leg was skipped and stored data returned instead. Never sent from the cutoff date" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "402": { "description": "Deprecated with filter.sat. Insufficient satellite credits and no stored position to fall back on. Not returned from the cutoff date, when filter.sat is ignored", "schema": { "$ref": "#/definitions/PaymentRequiredErrorResponse" } }, "403": { "description": "filter.satMaxAgeMinutes sent on a plan that does not include it (until the cutoff date, after which it is ignored), or API key temporarily suspended for sustained quota abuse (see Retry-After header)", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/NotFoundErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } }, "/v1/vessels/positions": { "get": { "security": [ { "ApiKeyAuth": [] } ], "description": "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.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Vessels" ], "summary": "Get positions for multiple vessels", "parameters": [ { "type": "string", "example": "232003239,246497000", "description": "MMSI or IMO number(s): comma-separated in one param, or repeat filter.ids for multiple", "name": "filter.ids", "in": "query", "required": true }, { "enum": [ "mmsi", "imo" ], "type": "string", "example": "mmsi", "description": "Identifier type: 'mmsi' or 'imo'", "name": "filter.idType", "in": "query", "required": true }, { "type": "string", "description": "Start timestamp in RFC3339 format (defaults to 2 hours ago)", "name": "time.from", "in": "query" }, { "type": "string", "description": "End timestamp in RFC3339 format (defaults to current time)", "name": "time.to", "in": "query" }, { "type": "integer", "default": 20, "description": "Maximum number of items to return, must be between 1 and 50", "name": "pagination.limit", "in": "query" }, { "type": "string", "description": "Pagination token for retrieving the next page of results", "name": "pagination.nextToken", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VesselPositionsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/BadRequestErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/AuthenticationErrorResponse" } }, "403": { "description": "API key temporarily suspended for sustained quota abuse; see Retry-After header", "schema": { "$ref": "#/definitions/ForbiddenErrorResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/RateLimitErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/InternalServerErrorResponse" } } } } } }, "definitions": { "AuthenticationErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "invalid_api_key" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "api key is invalid or not found" }, "type": { "description": "Type categorizes the error (always \"authentication_error\" for 401s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "authentication_error" } } }, "AuthenticationErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/AuthenticationErrorDetail" } } }, "BadRequestErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "invalid_mmsi" }, "doc_url": { "description": "DocURL is a link to documentation for more information", "type": "string", "example": "https://vesselapi.com/docs#invalid_mmsi" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "Invalid MMSI: abc123" }, "param": { "description": "Param identifies the parameter that caused the error (if applicable)", "type": "string", "example": "mmsi" }, "type": { "description": "Type categorizes the error (e.g., \"invalid_request_error\")", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "invalid_request_error" } } }, "BadRequestErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/BadRequestErrorDetail" } } }, "DGPSStation": { "description": "Differential GPS (DGPS) correction signal broadcast station", "type": "object", "properties": { "aid_type": { "description": "Type of navigational aid", "type": "string", "example": "DGPS" }, "delete_flag": { "description": "Deletion status flag", "type": "string" }, "feature_number": { "description": "NGA feature number identifier", "type": "number", "example": 1234.5 }, "frequency": { "description": "Broadcast frequency in kHz", "type": "number", "example": 290 }, "geopolitical_heading": { "description": "Country or major geographic area", "type": "string", "example": "UNITED STATES" }, "location": { "description": "GeoJSON point for geospatial queries", "allOf": [ { "$ref": "#/definitions/GeoJSON" } ] }, "name": { "description": "Station name", "type": "string", "example": "Cape Henry DGPS" }, "notice_number": { "description": "Notice to Mariners number", "type": "integer", "example": 12 }, "notice_week": { "description": "Week of the notice", "type": "string", "example": "15" }, "notice_year": { "description": "Year of the notice", "type": "string", "example": "2024" }, "position": { "description": "Human-readable position description", "type": "string", "example": "36°55.5'N 76°00.3'W" }, "post_note": { "description": "Notes appearing after the main entry", "type": "string" }, "preceding_note": { "description": "Notes appearing before the main entry", "type": "string" }, "range": { "description": "Signal range in nautical miles", "type": "integer", "example": 100 }, "region_heading": { "description": "Regional geographic subdivision", "type": "string", "example": "EAST COAST" }, "remarks": { "description": "Additional remarks about the station", "type": "string" }, "remove_from_list": { "description": "Flag indicating if entry should be removed", "type": "string" }, "station_id": { "description": "Station identifier code", "type": "string", "example": "852" }, "transfer_rate": { "description": "Data transfer rate in bits per second", "type": "integer", "example": 200 }, "volume_number": { "description": "NGA publication volume number", "type": "string", "example": "PUB 117" } } }, "DGPSStationsWithinLocationResponse": { "description": "Response containing DGPS stations within location data", "type": "object", "properties": { "dgpsStations": { "type": "array", "items": { "$ref": "#/definitions/DGPSStation" } }, "nextToken": { "type": "string" } } }, "ErrorCode": { "type": "string", "enum": [ "resource_missing", "invalid_parameter", "invalid_mmsi", "invalid_imo", "invalid_coordinates", "invalid_time_range", "bounding_box_too_dense", "missing_parameter", "invalid_api_key", "rate_limit_exceeded", "forbidden", "conflict", "notification_inactive", "prefill_pending", "insufficient_credits", "feature_not_available", "endpoint_retired", "internal_error", "database_error", "service_unavailable" ], "x-enum-varnames": [ "ErrorCodeResourceMissing", "ErrorCodeInvalidParameter", "ErrorCodeInvalidMMSI", "ErrorCodeInvalidIMO", "ErrorCodeInvalidCoordinates", "ErrorCodeInvalidTimeRange", "ErrorCodeBoundingBoxTooDense", "ErrorCodeMissingParameter", "ErrorCodeInvalidAPIKey", "ErrorCodeRateLimitExceeded", "ErrorCodeForbidden", "ErrorCodeConflict", "ErrorCodeNotificationInactive", "ErrorCodePrefillPending", "ErrorCodeInsufficientCredits", "ErrorCodeFeatureNotAvailable", "ErrorCodeEndpointRetired", "ErrorCodeInternalError", "ErrorCodeDatabaseError", "ErrorCodeServiceUnavailable" ] }, "ErrorType": { "type": "string", "enum": [ "invalid_request_error", "api_error", "authentication_error", "rate_limit_error", "forbidden_error", "not_found_error", "conflict_error", "payment_required_error", "service_unavailable_error", "gone_error" ], "x-enum-varnames": [ "ErrorTypeInvalidRequest", "ErrorTypeAPIError", "ErrorTypeAuthenticationError", "ErrorTypeRateLimitError", "ErrorTypeForbidden", "ErrorTypeNotFoundError", "ErrorTypeConflict", "ErrorTypePaymentRequired", "ErrorTypeServiceUnavailable", "ErrorTypeGone" ] }, "FindDGPSStationsResponse": { "description": "Response containing dgps station data", "type": "object", "properties": { "dgpsStations": { "type": "array", "items": { "$ref": "#/definitions/DGPSStation" } }, "nextToken": { "type": "string" } } }, "FindLightAidsResponse": { "description": "Response containing light aid data", "type": "object", "properties": { "lightAids": { "type": "array", "items": { "$ref": "#/definitions/LightAid" } }, "nextToken": { "type": "string" } } }, "FindMODUsResponse": { "description": "Query parameters for finding modu by name", "type": "object", "properties": { "modus": { "type": "array", "items": { "$ref": "#/definitions/MODU" } }, "nextToken": { "type": "string" } } }, "FindPortsResponse": { "description": "Response containing port data", "type": "object", "properties": { "nextToken": { "type": "string" }, "ports": { "type": "array", "items": { "$ref": "#/definitions/Port" } } } }, "FindRadioBeaconsResponse": { "description": "Response containing radio beacon data", "type": "object", "properties": { "nextToken": { "type": "string" }, "radioBeacons": { "type": "array", "items": { "$ref": "#/definitions/RadioBeacon" } } } }, "FindVesselsResponse": { "description": "Query parameters for finding vessels by name", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/VesselSearchMeta" }, "nextToken": { "type": "string" }, "vessels": { "type": "array", "items": { "$ref": "#/definitions/Vessel" } } } }, "ForbiddenErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "feature_not_available" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "this feature is not available on the \"free\" plan" }, "type": { "description": "Type categorizes the error (always \"forbidden_error\" for 403s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "forbidden_error" } } }, "ForbiddenErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/ForbiddenErrorDetail" } } }, "GeoJSON": { "description": "GeoJSON Point geometry for geospatial coordinates", "type": "object", "properties": { "coordinates": { "description": "Array of [longitude, latitude] in decimal degrees", "type": "array", "items": { "type": "number" }, "example": [ 103.8215, 1.2644 ] }, "type": { "description": "GeoJSON geometry type, always \"Point\" for location data", "type": "string", "example": "Point" } } }, "InternalServerErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "internal_error" }, "error_id": { "description": "ErrorID is a unique identifier for tracking this error (always present for 500 errors)", "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "An internal error occurred. Please reference error ID 550e8400-e29b-41d4-a716-446655440000 when contacting support if this issue persists." }, "timestamp": { "description": "Timestamp when the error occurred (ISO 8601 format)", "type": "string", "example": "2025-10-31T15:30:45Z" }, "type": { "description": "Type categorizes the error (always \"api_error\" for 500s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "api_error" } } }, "InternalServerErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/InternalServerErrorDetail" } } }, "LightAid": { "description": "Navigational light aid including lighthouses, buoys, and beacons", "type": "object", "properties": { "aid_type": { "description": "Type of navigational aid (Light, Buoy, Beacon, etc.)", "type": "string", "example": "Light" }, "characteristic": { "description": "Light flash pattern description (e.g., Fl W 7.5s)", "type": "string", "example": "Fl W 7.5s" }, "characteristic_number": { "description": "Light characteristic code number", "type": "integer" }, "delete_flag": { "description": "Deletion status flag", "type": "string" }, "feature_number": { "description": "NGA feature number identifier", "type": "string", "example": "590" }, "geopolitical_heading": { "description": "Country or major geographic area", "type": "string", "example": "UNITED STATES" }, "height_feet_meters": { "description": "Height of light above water in feet and meters", "type": "string", "example": "192ft 59m" }, "local_heading": { "description": "Local area description", "type": "string", "example": "Cape Hatteras" }, "location": { "description": "GeoJSON point for geospatial queries", "allOf": [ { "$ref": "#/definitions/GeoJSON" } ] }, "name": { "description": "Name of the light aid", "type": "string", "example": "Cape Hatteras Light" }, "notice_number": { "description": "Notice to Mariners number", "type": "integer" }, "notice_week": { "description": "Week of the notice", "type": "string" }, "notice_year": { "description": "Year of the notice", "type": "string" }, "position": { "description": "Human-readable position description", "type": "string", "example": "35°15.1'N 75°31.6'W" }, "post_note": { "description": "Notes appearing after the main entry", "type": "string" }, "preceding_note": { "description": "Notes appearing before the main entry", "type": "string" }, "range": { "description": "Nominal range of light in nautical miles", "type": "string", "example": "24" }, "region_heading": { "description": "Regional geographic subdivision", "type": "string", "example": "EAST COAST" }, "remarks": { "description": "Additional remarks about the light", "type": "string" }, "remove_from_list": { "description": "Flag indicating if entry should be removed", "type": "string" }, "structure": { "description": "Description of the physical structure", "type": "string", "example": "Black and white spiral bands" }, "subregion_heading": { "description": "Sub-regional geographic area", "type": "string", "example": "North Carolina" }, "volume_number": { "description": "NGA publication volume number", "type": "string", "example": "PUB 110" } } }, "LightAidsWithinLocationResponse": { "description": "Response containing light aids within location data", "type": "object", "properties": { "lightAids": { "type": "array", "items": { "$ref": "#/definitions/LightAid" } }, "nextToken": { "type": "string" } } }, "MODU": { "description": "Mobile Offshore Drilling Unit (MODU) location and status information", "type": "object", "properties": { "date": { "description": "Date of the position report (parsed from API string format YYYY-MM-DD)", "type": "string" }, "distance": { "description": "Distance from reference point in nautical miles", "type": "number" }, "latitude": { "description": "Geographic latitude in decimal degrees", "type": "number", "example": 28.7381 }, "location": { "description": "GeoJSON point for geospatial queries", "allOf": [ { "$ref": "#/definitions/GeoJSON" } ] }, "longitude": { "description": "Geographic longitude in decimal degrees", "type": "number", "example": -88.3659 }, "name": { "description": "Name of the drilling unit", "type": "string", "example": "DEEPWATER HORIZON" }, "navigation_area": { "description": "NAVAREA designation", "type": "string", "example": "IV" }, "position": { "description": "Human-readable position description", "type": "string", "example": "Gulf of Mexico" }, "region": { "description": "NGA region code", "type": "integer", "example": 8 }, "rig_status": { "description": "Current operational status of the rig", "type": "string", "example": "Drilling" }, "special_status": { "description": "Any special status or notes", "type": "string" }, "sub_region": { "description": "NGA sub-region code", "type": "integer", "example": 81 } } }, "MODUsWithinLocationResponse": { "description": "Response containing MODUs within location data", "type": "object", "properties": { "modus": { "type": "array", "items": { "$ref": "#/definitions/MODU" } }, "nextToken": { "type": "string" } } }, "MarineCasualtiesResponse": { "description": "Response containing marine casualty data", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "casualties": { "type": "array", "items": { "$ref": "#/definitions/MarineCasualty" } }, "nextToken": { "type": "string" } } }, "MarineCasualty": { "type": "object", "properties": { "atCoding": { "type": "array", "items": { "type": "string" } }, "casualtyReportNr": { "type": "string" }, "cfCoding": { "type": "array", "items": { "type": "string" } }, "collectedAt": { "description": "Record metadata (added when the record was stored)", "type": "string" }, "competentAuthority": { "type": "array", "items": { "type": "string" } }, "dateOfOccurrence": { "description": "Event details", "type": "string" }, "deviation": { "type": "array", "items": { "type": "string" } }, "eventType": { "type": "array", "items": { "type": "string" } }, "finishedInvestigation": { "type": "boolean" }, "imoNr": { "type": "array", "items": { "type": "string" } }, "interimReport": { "type": "boolean" }, "investigatingState": { "description": "Investigation", "type": "string" }, "livesLostTotal": { "description": "Consequences", "type": "string" }, "nameOfShip": { "description": "Vessel info (arrays since multiple vessels can be involved)", "type": "array", "items": { "type": "string" } }, "occurrenceSeverity": { "type": "string" }, "occurrenceUuid": { "description": "External IDs", "type": "string" }, "occurrenceWithPersons": { "type": "array", "items": { "type": "string" } }, "occurrenceWithShips": { "description": "Taxonomy classifications", "type": "array", "items": { "type": "string" } }, "peopleInjuredTotal": { "type": "string" }, "pollution": { "type": "boolean" }, "shipCraftType": { "type": "array", "items": { "type": "string" } }, "srCoding": { "type": "array", "items": { "type": "string" } } } }, "NotFoundErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "resource_missing" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "Vessel not found: 123456789" }, "type": { "description": "Type categorizes the error (always \"not_found_error\" for 404s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "not_found_error" } } }, "NotFoundErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/NotFoundErrorDetail" } } }, "PaymentRequiredErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "insufficient_credits" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "insufficient satellite credits" }, "type": { "description": "Type categorizes the error (always \"payment_required_error\" for 402s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "payment_required_error" } } }, "PaymentRequiredErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/PaymentRequiredErrorDetail" } } }, "Port": { "description": "Port information including facilities, services, and characteristics where available", "type": "object", "properties": { "anchorage_depth": { "description": "Depth at the anchorage area", "type": "number", "example": 20 }, "anchorage_depth_unit": { "description": "Unit for anchorage depth measurement", "type": "string", "example": "m" }, "cargo_handling_depth": { "description": "Depth at cargo handling berths", "type": "number", "example": 18 }, "cargo_handling_depth_unit": { "description": "Unit for cargo handling depth measurement", "type": "string", "example": "m" }, "channel_depth": { "description": "Depth of the approach channel", "type": "number", "example": 23 }, "channel_depth_unit": { "description": "Unit for channel depth measurement", "type": "string", "example": "m" }, "country": { "description": "Country information for the port", "allOf": [ { "$ref": "#/definitions/github_com_vesselapi_common_vessel-data-contracts_types.PortCountry" } ] }, "garbage_disposal": { "description": "Whether garbage disposal services are available", "type": "boolean", "example": true }, "harbor_size": { "description": "Harbor size classification (Large/Medium/Small/Very Small)", "type": "string", "example": "Large" }, "harbor_type": { "description": "Type of harbor (CB=Coastal Breakwater, CN=Coastal Natural, etc.)", "type": "string", "example": "CN" }, "harbor_use": { "description": "Primary use of the harbor (FISH/MIL/CARGO/FERRY/UNK)", "type": "string", "example": "CARGO" }, "has_drydock": { "description": "Whether the port has drydock facilities", "type": "boolean", "example": true }, "latitude": { "description": "Geographic latitude in decimal degrees", "type": "number", "example": 1.2644 }, "location": { "description": "GeoJSON point for geospatial queries", "allOf": [ { "$ref": "#/definitions/GeoJSON" } ] }, "longitude": { "description": "Geographic longitude in decimal degrees", "type": "number", "example": 103.8215 }, "max_vessel_beam": { "description": "Maximum beam (width) of vessel that can be accommodated", "type": "number", "example": 60 }, "max_vessel_beam_unit": { "description": "Unit for maximum vessel beam", "type": "string", "example": "m" }, "max_vessel_draft": { "description": "Maximum draft of vessel that can be accommodated", "type": "number", "example": 16 }, "max_vessel_draft_unit": { "description": "Unit for maximum vessel draft", "type": "string", "example": "m" }, "max_vessel_length": { "description": "Maximum length of vessel that can be accommodated", "type": "number", "example": 400 }, "max_vessel_length_unit": { "description": "Unit for maximum vessel length", "type": "string", "example": "m" }, "medical_facilities": { "description": "Whether medical facilities are available at the port", "type": "boolean", "example": true }, "name": { "description": "The port's official name", "type": "string", "example": "Singapore" }, "navigation_area": { "description": "NAVAREA designation for maritime safety communications", "type": "string", "example": "XI" }, "pilotage_available": { "description": "Whether pilotage services are available", "type": "boolean", "example": true }, "pilotage_compulsory": { "description": "Whether pilotage is mandatory for vessel entry", "type": "boolean", "example": true }, "port_security": { "description": "Whether ISPS (International Ship and Port Facility Security) compliant", "type": "boolean", "example": true }, "region_name": { "description": "Geographic region where the port is located", "type": "string", "example": "Southeast Asia" }, "repair_capability": { "description": "Level of ship repair capability (Major/Moderate/Limited/Emergency/None)", "type": "string", "example": "Major" }, "shelter": { "description": "Quality of shelter from weather (Excellent/Good/Fair/Poor/None)", "type": "string", "example": "Excellent" }, "size": { "description": "Size classification of the port", "type": "string", "example": "Large" }, "supply_diesel": { "description": "Whether diesel supply is available", "type": "boolean", "example": true }, "supply_fuel": { "description": "Whether fuel oil supply is available", "type": "boolean", "example": true }, "supply_water": { "description": "Whether fresh water supply is available", "type": "boolean", "example": true }, "traffic_separation_scheme": { "description": "Whether a TSS (Traffic Separation Scheme) is in place", "type": "boolean", "example": true }, "tugs_available": { "description": "Whether tug services are available", "type": "boolean", "example": true }, "type": { "description": "Port classification type", "type": "string", "example": "Seaport" }, "unlo_code": { "description": "UN Location Code (LOCODE) - unique port identifier", "type": "string", "example": "SGSIN" }, "vessel_traffic_service": { "description": "Whether VTS (Vessel Traffic Service) is operational", "type": "boolean", "example": true } } }, "PortEvent": { "description": "Vessel port call event including arrivals and departures", "type": "object", "properties": { "event": { "description": "Type of port event - either \"Arrival\" or \"Departure\"", "type": "string", "example": "Arrival" }, "port": { "description": "Reference to the port where the event occurred", "allOf": [ { "$ref": "#/definitions/PortReference" } ] }, "timestamp": { "description": "UTC timestamp when the event occurred", "type": "string" }, "vessel": { "description": "Reference to the vessel involved in the port event", "allOf": [ { "$ref": "#/definitions/VesselReference" } ] } } }, "PortEventResponse": { "description": "Response containing a single port event", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "portEvent": { "$ref": "#/definitions/PortEvent" } } }, "PortEventsResponse": { "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "nextToken": { "type": "string" }, "portEvents": { "type": "array", "items": { "$ref": "#/definitions/PortEvent" } } } }, "PortInboundResponse": { "description": "Response containing vessels heading to a port", "type": "object", "properties": { "nextToken": { "type": "string" }, "vesselETAs": { "type": "array", "items": { "$ref": "#/definitions/VesselETA" } } } }, "PortReference": { "description": "Port identification details for port event reference", "type": "object", "properties": { "country": { "description": "Country where the port is located", "type": "string", "example": "Singapore" }, "name": { "description": "The port's official name", "type": "string", "example": "Singapore" }, "unlo_code": { "description": "UN Location Code (LOCODE) for the port", "type": "string", "example": "SGSIN" } } }, "PortResponse": { "description": "Response containing a single port", "type": "object", "properties": { "port": { "$ref": "#/definitions/Port" } } }, "PortsWithinLocationResponse": { "description": "Response containing ports within location data", "type": "object", "properties": { "nextToken": { "type": "string" }, "ports": { "type": "array", "items": { "$ref": "#/definitions/Port" } } } }, "PositionCheck": { "type": "object", "properties": { "distance_nm": { "description": "Great-circle distance from the previous position, in nautical miles", "type": "number", "example": 96.3 }, "exceeds_typical_speed": { "description": "True when the implied speed is more than 1.2 times the vessel's usual top speed (99th percentile of its recent speeds)", "type": "boolean", "example": false }, "identity_match": { "description": "True when the returned position's MMSI and IMO match the identifiers in our vessel record. Omitted when we hold no record or nothing can be compared.", "type": "boolean", "example": true }, "implied_course": { "description": "Initial great-circle bearing from the previous position, in degrees from true north", "type": "integer", "example": 87 }, "implied_speed_kn": { "description": "Average speed needed to cover that distance in that time, in knots", "type": "number", "example": 14 }, "lookback_hours": { "description": "How far back the previous position was searched for", "type": "integer", "example": 80 }, "minutes_since_previous": { "description": "Minutes between the previous position and the returned one", "type": "integer", "example": 412 }, "previous_position": { "description": "The vessel's newest earlier position report within lookback_hours that is not a suspected glitch", "allOf": [ { "$ref": "#/definitions/PreviousPosition" } ] } } }, "PreviousPosition": { "type": "object", "properties": { "latitude": { "description": "Latitude of the previous position in decimal degrees", "type": "number", "example": 1.2644 }, "longitude": { "description": "Longitude of the previous position in decimal degrees", "type": "number", "example": 103.8215 }, "timestamp": { "description": "When the previous position was reported (UTC)", "type": "string", "example": "2026-10-24T03:10:00Z" } } }, "RadioBeacon": { "description": "Navigational radio beacon for maritime direction finding", "type": "object", "properties": { "aid_type": { "description": "Type of radio aid", "type": "string", "example": "RBn" }, "characteristic": { "description": "Beacon transmission characteristic", "type": "string", "example": "A (.--)" }, "delete_flag": { "description": "Deletion status flag", "type": "string" }, "feature_number": { "description": "NGA feature number identifier", "type": "number", "example": 456 }, "frequency": { "description": "Broadcast frequency", "type": "string", "example": "286 kHz" }, "geopolitical_heading": { "description": "Country or major geographic area", "type": "string", "example": "UNITED STATES" }, "location": { "description": "GeoJSON point for geospatial queries", "allOf": [ { "$ref": "#/definitions/GeoJSON" } ] }, "name": { "description": "Name of the radio beacon", "type": "string", "example": "Ambrose Light" }, "notice_number": { "description": "Notice to Mariners number", "type": "integer" }, "notice_week": { "description": "Week of the notice", "type": "string" }, "notice_year": { "description": "Year of the notice", "type": "string" }, "position": { "description": "Human-readable position description", "type": "string", "example": "40°27.1'N 73°49.5'W" }, "post_note": { "description": "Notes appearing after the main entry", "type": "string" }, "preceding_note": { "description": "Notes appearing before the main entry", "type": "string" }, "range": { "description": "Signal range in nautical miles", "type": "string", "example": "20" }, "region_heading": { "description": "Regional geographic subdivision", "type": "string", "example": "EAST COAST" }, "remove_from_list": { "description": "Flag indicating if entry should be removed", "type": "string" }, "sequence_text": { "description": "Transmission sequence description", "type": "string" }, "station_remark": { "description": "Remarks specific to the station", "type": "string" }, "volume_number": { "description": "NGA publication volume number", "type": "string", "example": "PUB 117" } } }, "RadioBeaconsWithinLocationResponse": { "description": "Response containing radio beacons within location data", "type": "object", "properties": { "nextToken": { "type": "string" }, "radioBeacons": { "type": "array", "items": { "$ref": "#/definitions/RadioBeacon" } } } }, "RateLimitErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "rate_limit_exceeded" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "API monthly quota exceeded" }, "type": { "description": "Type categorizes the error (always \"rate_limit_error\" for 429s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "rate_limit_error" } } }, "RateLimitErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/RateLimitErrorDetail" } } }, "ServiceUnavailableErrorDetail": { "type": "object", "properties": { "code": { "description": "Code is a short string identifier for this error for programmatic handling", "allOf": [ { "$ref": "#/definitions/ErrorCode" } ], "example": "service_unavailable" }, "message": { "description": "Message is a human-readable message providing more details about the error", "type": "string", "example": "The service is temporarily unavailable. Retry after a brief delay." }, "type": { "description": "Type categorizes the error (always \"service_unavailable_error\" for 503s)", "allOf": [ { "$ref": "#/definitions/ErrorType" } ], "example": "service_unavailable_error" } } }, "ServiceUnavailableErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/definitions/ServiceUnavailableErrorDetail" } } }, "Vessel": { "description": "Vessel static data including identification, dimensions, and capacities where available", "type": "object", "properties": { "breadth": { "description": "Maximum beam (width) of the vessel", "type": "integer", "example": 59 }, "breadth_unit": { "description": "Unit of measurement for breadth (typically meters)", "type": "string", "example": "m" }, "call_sign": { "description": "International radio call sign assigned to the vessel", "type": "string", "example": "H3RC" }, "country": { "description": "Country of registration (flag state)", "type": "string", "example": "Panama" }, "country_code": { "description": "ISO 2-letter country code of flag state", "type": "string", "example": "PA" }, "deadweight_tonnage": { "description": "Deadweight tonnage (DWT) - maximum cargo capacity in metric tons", "type": "integer", "example": 199629 }, "draft": { "description": "Maximum draft (depth below waterline) of the vessel", "type": "integer", "example": 16 }, "draft_unit": { "description": "Unit of measurement for draft (typically meters)", "type": "string", "example": "m" }, "draught_calculated_avg": { "description": "Arithmetic mean of reported draught in metres over the last 31 days of ETA messages (zero readings excluded).", "type": "number", "example": 13.8 }, "draught_observed_max": { "description": "Largest reported draught in metres over the last 31 days of ETA messages. Distinct from summer_draught (the design value).", "type": "number", "example": 16 }, "engine_model_name": { "description": "Model name of the main engine", "type": "string" }, "engine_type": { "description": "Type code for the main engine", "type": "integer" }, "eni": { "description": "European Number of Identification for inland waterway vessels (8 digits)", "type": "string" }, "former_names": { "description": "List of previous names the vessel has operated under", "type": "array", "items": { "$ref": "#/definitions/github_com_vesselapi_common_vessel-data-contracts_types.VesselFormerName" } }, "gross_tonnage": { "description": "Gross tonnage (GT) - measure of vessel's overall internal volume", "type": "integer", "example": 220940 }, "home_port": { "description": "Port of registry for the vessel", "type": "string", "example": "Panama City" }, "imo": { "description": "International Maritime Organization number - permanent 7-digit vessel identifier", "type": "integer", "example": 9811000 }, "kilowatt_power": { "description": "Main engine power in kilowatts", "type": "integer", "example": 58000 }, "length": { "description": "Overall length of the vessel", "type": "integer", "example": 400 }, "length_unit": { "description": "Unit of measurement for length (typically meters)", "type": "string", "example": "m" }, "mmsi": { "description": "Maritime Mobile Service Identity - 9-digit radio identifier", "type": "integer", "example": 353136000 }, "name": { "description": "The vessel's current registered name", "type": "string", "example": "EVER GIVEN" }, "name_ais": { "description": "The name as currently broadcast on AIS. It may differ from the registered name for a short time after a rename, until our next registry update.", "type": "string", "example": "EVER GIVEN" }, "operating_status": { "description": "Current operational status (e.g., Active, Laid Up, Scrapped)", "type": "string", "example": "Active" }, "speed_calculated_avg": { "description": "Arithmetic mean of speed over ground in knots over a recent 31-day window of position reports, computed from this vessel's AIS history (stops excluded). It is derived from our observations and is distinct from the design service speed.", "type": "number", "example": 12.4 }, "speed_observed_max": { "description": "Usual top speed: the 99th percentile of speed over ground in knots over a recent 31-day window, capped at 40 knots to discard GPS glitches.", "type": "number", "example": 22.1 }, "summer_draught": { "description": "Maximum design draught (summer-load line). Static vessel attribute, distinct from draught_observed_max.", "type": "number", "example": 16.5 }, "teu": { "description": "Twenty-foot equivalent unit container capacity. Populated only for container ships.", "type": "integer", "example": 23992 }, "vessel_subtype": { "description": "Finer-grained classification beyond vessel_type (e.g., inland motor cargo or tanker vessel).", "type": "string" }, "vessel_type": { "description": "Classification of vessel type (e.g., Container Ship, Bulk Carrier)", "type": "string", "example": "Cargo A" }, "year_built": { "description": "Year the vessel was constructed", "type": "integer", "example": 2018 } } }, "VesselETA": { "description": "Vessel Estimated Time of Arrival information from AIS static/voyage data", "type": "object", "properties": { "destination": { "description": "Reported destination port or area as entered by the vessel", "type": "string", "example": "SINGAPORE" }, "destination_port": { "description": "Resolved UN/LOCODE of the destination port (empty if unresolved)", "type": "string", "example": "NLRTM" }, "draught": { "description": "Current draught (draft) of the vessel in meters", "type": "number", "example": 14.5 }, "eta": { "description": "Estimated time of arrival at destination as reported by the vessel", "type": "string" }, "imo": { "description": "International Maritime Organization number - permanent vessel identifier", "type": "integer", "example": 9811000 }, "mmsi": { "description": "Maritime Mobile Service Identity - unique 9-digit vessel identifier", "type": "integer", "example": 353136000 }, "timestamp": { "description": "UTC timestamp when this ETA information was received", "type": "string" }, "vessel_name": { "description": "The vessel's registered name as reported in AIS", "type": "string", "example": "EVER GIVEN" } } }, "VesselETAResponse": { "description": "Response containing vessel ETA data", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "vesselEta": { "$ref": "#/definitions/VesselETA" } } }, "VesselEmission": { "type": "object", "properties": { "co2_emissions_at_berth": { "type": "number" }, "co2_emissions_on_laden_voyages": { "type": "number" }, "co2_emissions_total": { "description": "CO2 emissions", "type": "number" }, "co2_per_distance": { "description": "kg CO₂ / n mile", "type": "number" }, "co2_per_transport_work": { "description": "g CO₂ / m tonnes · n miles", "type": "number" }, "collected_at": { "type": "string" }, "distance_through_ice": { "description": "nautical miles", "type": "number" }, "doc_expiry_date": { "type": "string" }, "doc_issue_date": { "description": "DOC info", "type": "string" }, "flag_code": { "type": "string" }, "flag_name": { "type": "string" }, "fuel_consumption_hfo": { "type": "number" }, "fuel_consumption_lfo": { "type": "number" }, "fuel_consumption_lng": { "type": "number" }, "fuel_consumption_mdo": { "type": "number" }, "fuel_consumption_mgo": { "type": "number" }, "fuel_consumption_other": { "type": "number" }, "fuel_consumption_total": { "description": "Fuel consumption (tonnes)", "type": "number" }, "fuel_per_distance": { "description": "Efficiency metrics (pre-calculated)", "type": "number" }, "fuel_per_transport_work": { "description": "g / m tonnes · n miles", "type": "number" }, "home_port": { "type": "string" }, "ice_class": { "type": "string" }, "imo": { "description": "Identifiers", "type": "integer" }, "monitoring_method_a": { "description": "Monitoring method", "type": "string" }, "monitoring_method_b": { "type": "string" }, "monitoring_method_c": { "type": "string" }, "monitoring_method_d": { "type": "string" }, "name": { "type": "string" }, "port_calls_outside_eu": { "type": "integer" }, "port_calls_within_eu": { "description": "EU specific", "type": "integer" }, "reporting_period": { "description": "Reporting period", "type": "string" }, "technical_efficiency": { "description": "Technical efficiency", "type": "string" }, "technical_efficiency_value": { "type": "number" }, "time_at_sea_through_ice": { "description": "hours", "type": "number" }, "total_time_at_sea": { "description": "Distance and time", "type": "number" }, "unique_key": { "description": "Stable identifier for this emission record (IMO + reporting period)", "type": "string" }, "verifier_accreditation": { "type": "string" }, "verifier_address": { "type": "string" }, "verifier_name": { "description": "Verifier info", "type": "string" }, "vessel_type": { "description": "Vessel identification", "type": "string" } } }, "VesselEmissionsResponse": { "description": "Response containing vessel emissions data", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "emissions": { "type": "array", "items": { "$ref": "#/definitions/VesselEmission" } }, "nextToken": { "type": "string" } } }, "VesselPosition": { "description": "Vessel position report derived from AIS messages", "type": "object", "properties": { "cog": { "description": "Course Over Ground in degrees (0-359.9), null when unavailable", "type": "number", "example": 231.5 }, "heading": { "description": "True heading in degrees (0-359), null when unavailable", "type": "integer", "example": 230 }, "imo": { "description": "International Maritime Organization number - permanent vessel identifier", "type": "integer", "example": 9811000 }, "latitude": { "description": "Geographic latitude in decimal degrees (-90 to 90)", "type": "number", "example": 1.2644 }, "location": { "description": "GeoJSON point for geospatial queries", "allOf": [ { "$ref": "#/definitions/GeoJSON" } ] }, "longitude": { "description": "Geographic longitude in decimal degrees (-180 to 180)", "type": "number", "example": 103.8215 }, "mmsi": { "description": "Maritime Mobile Service Identity - unique 9-digit vessel identifier", "type": "integer", "example": 353136000 }, "nav_status": { "description": "AIS navigational status (0=under way using engine, 1=at anchor, 2=not under command, 3=restricted manoeuvrability, 5=moored, 8=under way sailing, etc.), null when unavailable", "type": "integer", "example": 0 }, "processed_timestamp": { "description": "UTC timestamp when the position was processed by the system", "type": "string" }, "sog": { "description": "Speed Over Ground in knots (0-102.2), null when unavailable", "type": "number", "example": 14.1 }, "suspected_glitch": { "description": "True when the position implies a speed over 500 knots from the vessel's previous clean report, which no vessel reaches. Such a fix is likely a GPS glitch or a corrupted AIS transmission.", "type": "boolean", "example": false }, "timestamp": { "description": "UTC timestamp when the AIS message was transmitted by the vessel", "type": "string" }, "vessel_name": { "description": "The vessel's registered name as reported in AIS", "type": "string", "example": "EVER GIVEN" } } }, "VesselPositionResponse": { "description": "Response containing a single vessel position", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "positionCheck": { "description": "How the returned position compares with the vessel's previous position report. The lookback_hours field is always present. The identity_match field is present when there is a record to compare against. The other fields need a previous report.", "allOf": [ { "$ref": "#/definitions/PositionCheck" } ] }, "vessel": { "description": "The vessel's particulars, as returned by GET /vessel/{id}. Omitted when the vessel is not in the registry.", "allOf": [ { "$ref": "#/definitions/Vessel" } ] }, "vesselEta": { "description": "The latest destination and ETA the vessel reported, as returned by GET /vessel/{id}/eta. Omitted when no destination or ETA is available, including when the lookup does not finish in time.", "allOf": [ { "$ref": "#/definitions/VesselETA" } ] }, "vesselPosition": { "$ref": "#/definitions/VesselPosition" } } }, "VesselPositionsResponse": { "description": "Response containing vessel position data", "type": "object", "properties": { "nextToken": { "type": "string" }, "vesselPositions": { "type": "array", "items": { "$ref": "#/definitions/VesselPosition" } } } }, "VesselReference": { "description": "Vessel identification details for port event reference", "type": "object", "properties": { "imo": { "description": "International Maritime Organization number", "type": "integer", "example": 9811000 }, "mmsi": { "description": "Maritime Mobile Service Identity number", "type": "integer", "example": 353136000 }, "name": { "description": "The vessel's registered name", "type": "string", "example": "EVER GIVEN" } } }, "VesselResponse": { "description": "Response containing vessel data", "type": "object", "properties": { "_meta": { "$ref": "#/definitions/types.ResolutionMeta" }, "vessel": { "$ref": "#/definitions/Vessel" } } }, "VesselSearchMeta": { "type": "object", "properties": { "matchedOn": { "description": "MatchedOn maps the index of a vessel in the vessels array to the fields\nthat matched it, e.g. {\"0\":[\"eni\"],\"1\":[\"imo\"]}. Values are arrays because\none vessel can match on several fields at once (a vessel whose ENI and IMO\nare the same digits). Field order within an entry is stable: eni, imo,\nmmsi, callsign, name.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "query": { "description": "Query echoes the q value the fields were matched against.", "type": "string", "example": "4606770" } } }, "VesselsWithinLocationResponse": { "description": "Response containing vessel within location data", "type": "object", "properties": { "nextToken": { "type": "string" }, "vessels": { "type": "array", "items": { "$ref": "#/definitions/VesselPosition" } } } }, "github_com_vesselapi_common_vessel-data-contracts_types.PortCountry": { "description": "Country information for port location", "type": "object", "properties": { "code": { "description": "ISO 2-letter country code", "type": "string", "example": "SG" }, "name": { "description": "Full country name", "type": "string", "example": "Singapore" } } }, "github_com_vesselapi_common_vessel-data-contracts_types.VesselFormerName": { "description": "Historical vessel name record", "type": "object", "properties": { "name": { "description": "Previous name of the vessel", "type": "string", "example": "EVER GREEN" }, "year_until": { "description": "Year until which this name was used", "type": "string", "example": "2018" } } }, "types.ResolutionMeta": { "type": "object", "properties": { "requestedIdType": { "type": "string" }, "resolvedId": { "type": "integer" }, "resolvedIdType": { "type": "string" }, "suggestedIdType": { "description": "When set, the caller may get a result by retrying with the opposite\nidentifier type. It is set only on a total miss where the counterpart id\nwas neither supplied nor derivable. It is phrased conditionally and does\nnot assert that the other id exists.", "type": "string" } } } }, "securityDefinitions": { "ApiKeyAuth": { "description": "API key authentication. Use the format: \"Bearer your_api_key_here\" in the Authorization header.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "description": "Retrieve vessel information including positions, static data, and estimated time of arrival by MMSI, IMO, name, or location", "name": "Vessels" }, { "description": "EU MRV-verified emissions and energy-efficiency metrics, plus marine casualty and incident records by vessel", "name": "Regulatory Records" }, { "description": "Access port call information including vessel arrivals, departures, and current port activity", "name": "Port Events" }, { "description": "Search world port index data by location, name, or geographic area", "name": "Ports" }, { "description": "Locate maritime navigation aids and infrastructure including DGPS stations, light aids, MODUs, and radio beacons by geographic coordinates or name", "name": "Navigation Infrastructure" } ] }