MaritimeService.openapi.yaml

openapi: 3.1.0
info:
    title: MaritimeService API
    version: 1.0.0
paths:
    /api/maritime/v1/get-vessel-snapshot:
        get:
            tags:
                - MaritimeService
            summary: GetVesselSnapshot
            description: GetVesselSnapshot retrieves a point-in-time view of AIS vessel traffic and disruptions.
            operationId: GetVesselSnapshot
            parameters:
                - name: ne_lat
                  in: query
                  description: North-east corner latitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
                - name: ne_lon
                  in: query
                  description: North-east corner longitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
                - name: sw_lat
                  in: query
                  description: South-west corner latitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
                - name: sw_lon
                  in: query
                  description: South-west corner longitude of bounding box.
                  required: false
                  schema:
                    type: number
                    format: double
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetVesselSnapshotResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidationError'
                default:
                    description: Error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
    /api/maritime/v1/list-navigational-warnings:
        get:
            tags:
                - MaritimeService
            summary: ListNavigationalWarnings
            description: ListNavigationalWarnings retrieves active maritime safety warnings from NGA.
            operationId: ListNavigationalWarnings
            parameters:
                - name: page_size
                  in: query
                  description: Maximum items per page (1-100).
                  required: false
                  schema:
                    type: integer
                    format: int32
                - name: cursor
                  in: query
                  description: Cursor for next page.
                  required: false
                  schema:
                    type: string
                - name: area
                  in: query
                  description: Optional area filter (e.g., "NAVAREA IV", "Persian Gulf").
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListNavigationalWarningsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidationError'
                default:
                    description: Error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
components:
    schemas:
        Error:
            type: object
            properties:
                message:
                    type: string
                    description: Error message (e.g., 'user not found', 'database connection failed')
            description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
        FieldViolation:
            type: object
            properties:
                field:
                    type: string
                    description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
                description:
                    type: string
                    description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
            required:
                - field
                - description
            description: FieldViolation describes a single validation error for a specific field.
        ValidationError:
            type: object
            properties:
                violations:
                    type: array
                    items:
                        $ref: '#/components/schemas/FieldViolation'
                    description: List of validation violations
            required:
                - violations
            description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
        GetVesselSnapshotRequest:
            type: object
            properties:
                neLat:
                    type: number
                    format: double
                    description: North-east corner latitude of bounding box.
                neLon:
                    type: number
                    format: double
                    description: North-east corner longitude of bounding box.
                swLat:
                    type: number
                    format: double
                    description: South-west corner latitude of bounding box.
                swLon:
                    type: number
                    format: double
                    description: South-west corner longitude of bounding box.
            description: GetVesselSnapshotRequest specifies filters for the vessel snapshot.
        GetVesselSnapshotResponse:
            type: object
            properties:
                snapshot:
                    $ref: '#/components/schemas/VesselSnapshot'
            description: GetVesselSnapshotResponse contains the vessel traffic snapshot.
        VesselSnapshot:
            type: object
            properties:
                snapshotAt:
                    type: integer
                    format: int64
                    description: 'Snapshot timestamp, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                densityZones:
                    type: array
                    items:
                        $ref: '#/components/schemas/AisDensityZone'
                disruptions:
                    type: array
                    items:
                        $ref: '#/components/schemas/AisDisruption'
            description: VesselSnapshot represents a point-in-time view of civilian AIS vessel data.
        AisDensityZone:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Zone identifier.
                name:
                    type: string
                    description: Zone name (e.g., "Strait of Malacca").
                location:
                    $ref: '#/components/schemas/GeoCoordinates'
                intensity:
                    type: number
                    maximum: 100
                    minimum: 0
                    format: double
                    description: Traffic intensity score (0-100).
                deltaPct:
                    type: number
                    format: double
                    description: Change from baseline as a percentage.
                shipsPerDay:
                    type: integer
                    format: int32
                    description: Estimated ships per day.
                note:
                    type: string
                    description: Analyst note.
            required:
                - id
            description: AisDensityZone represents a zone of concentrated vessel traffic.
        GeoCoordinates:
            type: object
            properties:
                latitude:
                    type: number
                    maximum: 90
                    minimum: -90
                    format: double
                    description: Latitude in decimal degrees (-90 to 90).
                longitude:
                    type: number
                    maximum: 180
                    minimum: -180
                    format: double
                    description: Longitude in decimal degrees (-180 to 180).
            description: GeoCoordinates represents a geographic location using WGS84 coordinates.
        AisDisruption:
            type: object
            properties:
                id:
                    type: string
                    minLength: 1
                    description: Disruption identifier.
                name:
                    type: string
                    description: Descriptive name.
                type:
                    type: string
                    enum:
                        - AIS_DISRUPTION_TYPE_UNSPECIFIED
                        - AIS_DISRUPTION_TYPE_GAP_SPIKE
                        - AIS_DISRUPTION_TYPE_CHOKEPOINT_CONGESTION
                    description: |-
                        AisDisruptionType represents the type of AIS tracking anomaly.
                         Maps to TS union: 'gap_spike' | 'chokepoint_congestion'.
                location:
                    $ref: '#/components/schemas/GeoCoordinates'
                severity:
                    type: string
                    enum:
                        - AIS_DISRUPTION_SEVERITY_UNSPECIFIED
                        - AIS_DISRUPTION_SEVERITY_LOW
                        - AIS_DISRUPTION_SEVERITY_ELEVATED
                        - AIS_DISRUPTION_SEVERITY_HIGH
                    description: AisDisruptionSeverity represents the severity of an AIS disruption.
                changePct:
                    type: number
                    format: double
                    description: Percentage change from normal.
                windowHours:
                    type: integer
                    format: int32
                    description: Analysis window in hours.
                darkShips:
                    type: integer
                    format: int32
                    description: Number of dark ships (AIS off) detected.
                vesselCount:
                    type: integer
                    format: int32
                    description: Number of vessels in the affected area.
                region:
                    type: string
                    description: Region name.
                description:
                    type: string
                    description: Human-readable description.
            required:
                - id
            description: AisDisruption represents a detected anomaly in AIS vessel tracking data.
        ListNavigationalWarningsRequest:
            type: object
            properties:
                pageSize:
                    type: integer
                    format: int32
                    description: Maximum items per page (1-100).
                cursor:
                    type: string
                    description: Cursor for next page.
                area:
                    type: string
                    description: Optional area filter (e.g., "NAVAREA IV", "Persian Gulf").
            description: ListNavigationalWarningsRequest specifies filters for retrieving NGA warnings.
        ListNavigationalWarningsResponse:
            type: object
            properties:
                warnings:
                    type: array
                    items:
                        $ref: '#/components/schemas/NavigationalWarning'
                pagination:
                    $ref: '#/components/schemas/PaginationResponse'
            description: ListNavigationalWarningsResponse contains navigational warnings matching the request.
        NavigationalWarning:
            type: object
            properties:
                id:
                    type: string
                    description: Warning identifier.
                title:
                    type: string
                    description: Warning title.
                text:
                    type: string
                    description: Full warning text.
                area:
                    type: string
                    description: Geographic area affected.
                location:
                    $ref: '#/components/schemas/GeoCoordinates'
                issuedAt:
                    type: integer
                    format: int64
                    description: 'Warning issue date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                expiresAt:
                    type: integer
                    format: int64
                    description: 'Warning expiry date, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript'
                authority:
                    type: string
                    description: Warning source authority.
            description: NavigationalWarning represents a maritime safety warning from NGA.
        PaginationResponse:
            type: object
            properties:
                nextCursor:
                    type: string
                    description: Cursor for fetching the next page. Empty string indicates no more pages.
                totalCount:
                    type: integer
                    format: int32
                    description: Total count of items matching the query, if known. Zero if the total is unknown.
            description: PaginationResponse contains pagination metadata returned alongside list results.