AISHub Vessel Positions API

openapi: 3.2.0
info:
  title: AISHub Web Service Stations Vessel Positions 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.
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
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.