openapi: 3.0.3
info:
  title: AISHub Web Service API
  description: >-
    HTTP web service for the AISHub AIS data-sharing network. Two endpoints on
    data.aishub.net return the latest vessel positions (ws.php) and receiving
    station metadata (stations.php) as XML, JSON, or CSV, with optional
    ZIP/GZIP/BZIP2 compression. Requests are authenticated with the member
    username issued when you join the network. Access is contribute-to-access -
    you must stream a raw NMEA AIS feed from your own receiver to AISHub (via
    UDP) and meet coverage/uptime quality thresholds to receive API
    credentials; access to the aggregated data is then free. Do not poll more
    frequently than once per minute - the service returns nothing when called
    more often. Endpoints, parameters, and defaults below are grounded in the
    published documentation at https://www.aishub.net/api; response schemas
    summarize the documented fields and are partially modeled where the docs
    do not enumerate exact types.
  version: '1.0'
  contact:
    name: AISHub
    url: https://www.aishub.net
servers:
  - url: https://data.aishub.net
    description: AISHub web service
tags:
  - name: Vessel Positions
    description: Latest known positions and voyage data for vessels tracked by the network.
  - name: Stations
    description: Metadata about the receiving stations that make up the network.
paths:
  /ws.php:
    get:
      operationId: getVesselPositions
      tags:
        - Vessel Positions
      summary: Get latest vessel positions
      description: >-
        Returns the latest known position and voyage data for vessels tracked
        by the AISHub network, filterable by bounding box, MMSI, IMO, and
        maximum position age. Poll no more than once per minute.
      parameters:
        - name: username
          in: query
          required: true
          description: AISHub member username (issued to qualifying feed contributors).
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: 'Value encoding: 0 = AIS encoding, 1 = human-readable. Default 0.'
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - name: output
          in: query
          required: false
          description: Output format. Default xml.
          schema:
            type: string
            enum: [xml, json, csv]
            default: xml
        - name: compress
          in: query
          required: false
          description: 'Compression: 0 = none, 1 = ZIP, 2 = GZIP, 3 = BZIP2. Default 0.'
          schema:
            type: integer
            enum: [0, 1, 2, 3]
            default: 0
        - name: latmin
          in: query
          required: false
          description: Southern boundary of bounding box (decimal degrees). Default -90.
          schema:
            type: number
            minimum: -90
            maximum: 90
            default: -90
        - name: latmax
          in: query
          required: false
          description: Northern boundary of bounding box (decimal degrees). Default 90.
          schema:
            type: number
            minimum: -90
            maximum: 90
            default: 90
        - name: lonmin
          in: query
          required: false
          description: Western boundary of bounding box (decimal degrees). Default -180.
          schema:
            type: number
            minimum: -180
            maximum: 180
            default: -180
        - name: lonmax
          in: query
          required: false
          description: Eastern boundary of bounding box (decimal degrees). Default 180.
          schema:
            type: number
            minimum: -180
            maximum: 180
            default: 180
        - name: mmsi
          in: query
          required: false
          description: Filter by vessel MMSI number(s).
          schema:
            type: string
        - name: imo
          in: query
          required: false
          description: Filter by vessel IMO number(s).
          schema:
            type: string
        - name: interval
          in: query
          required: false
          description: Maximum age of returned positions, in minutes.
          schema:
            type: integer
      responses:
        '200':
          description: >-
            Latest vessel positions in the requested output format. An empty
            body is returned when the once-per-minute polling limit is
            exceeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VesselPosition'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VesselPosition'
            text/csv:
              schema:
                type: string
  /stations.php:
    get:
      operationId: getStations
      tags:
        - Stations
      summary: Get receiving stations
      description: >-
        Returns metadata about the receiving stations contributing to the
        AISHub network, optionally filtered to a single station id.
      parameters:
        - name: username
          in: query
          required: true
          description: AISHub member username.
          schema:
            type: string
        - name: output
          in: query
          required: false
          description: Output format. Default xml.
          schema:
            type: string
            enum: [xml, json, csv]
            default: xml
        - name: compress
          in: query
          required: false
          description: 'Compression: 0 = none, 1 = ZIP, 2 = GZIP, 3 = BZIP2. Default 0.'
          schema:
            type: integer
            enum: [0, 1, 2, 3]
            default: 0
        - name: id
          in: query
          required: false
          description: Return only the station with this id.
          schema:
            type: string
      responses:
        '200':
          description: Station metadata in the requested output format.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Station'
            text/csv:
              schema:
                type: string
components:
  schemas:
    VesselPosition:
      type: object
      description: >-
        Latest known position and voyage data for one vessel. With format=0
        values use AIS encoding (e.g. coordinates in 1/600000 degree units);
        with format=1 values are human-readable. Field list per the
        documentation; exact property names/types are partially modeled.
      properties:
        MMSI:
          type: integer
          description: Maritime Mobile Service Identity of the vessel.
        TIME:
          type: string
          description: Timestamp of the last received position report.
        LATITUDE:
          type: number
          description: Latitude (AIS-encoded with format=0, decimal degrees with format=1).
        LONGITUDE:
          type: number
          description: Longitude (AIS-encoded with format=0, decimal degrees with format=1).
        COG:
          type: number
          description: Course over ground.
        SOG:
          type: number
          description: Speed over ground.
        HEADING:
          type: integer
          description: True heading.
        NAVSTAT:
          type: integer
          description: Navigational status.
        IMO:
          type: integer
          description: IMO ship identification number.
        NAME:
          type: string
          description: Vessel name.
        CALLSIGN:
          type: string
          description: Radio callsign.
        TYPE:
          type: integer
          description: AIS ship and cargo type.
        A:
          type: integer
          description: Dimension to bow (meters).
        B:
          type: integer
          description: Dimension to stern (meters).
        C:
          type: integer
          description: Dimension to port (meters).
        D:
          type: integer
          description: Dimension to starboard (meters).
        DRAUGHT:
          type: number
          description: Present draught.
        DEST:
          type: string
          description: Reported destination.
        ETA:
          type: string
          description: Reported estimated time of arrival.
    Station:
      type: object
      description: >-
        Metadata for one receiving station in the AISHub network. The
        documentation confirms the endpoint and its parameters but does not
        enumerate response fields; this schema is modeled.
      additionalProperties: true
      properties:
        ID:
          type: string
          description: Station identifier (modeled).