openapi: 3.1.0
info:
  title: MarineTraffic AIS Vessel Tracking API
  description: >-
    MarineTraffic AIS API provides real-time vessel position data from over 13,000
    AIS receivers globally. Returns vessel positions, speeds, headings, and voyage
    information for fleet monitoring, port operations, and supply chain visibility.
  version: 1.0.0
  contact:
    name: MarineTraffic / Kpler Support
    url: https://www.kpler.com/contact
  license:
    name: Proprietary
    url: https://www.kpler.com/company/terms-of-use
externalDocs:
  description: MarineTraffic API Documentation
  url: https://www.kpler.com/product/maritime/data-services
servers:
  - url: https://services.marinetraffic.com/api
    description: MarineTraffic REST API
security:
  - APIKey: []
paths:
  /exportvessel/{apikey}:
    get:
      operationId: getVesselDetails
      summary: Get vessel details
      description: >-
        Retrieve vessel characteristics and current static data from the
        MarineTraffic ship database including name, flag, type, dimensions,
        and registration details.
      tags:
        - Vessels
      parameters:
        - name: apikey
          in: path
          required: true
          schema:
            type: string
          description: Your MarineTraffic API key
        - name: v
          in: query
          schema:
            type: integer
            enum: [3, 4, 5]
            default: 4
          description: API version
        - name: MMSI
          in: query
          schema:
            type: string
            pattern: '^[0-9]{9}$'
          description: Maritime Mobile Service Identity number (9 digits)
        - name: IMO
          in: query
          schema:
            type: integer
          description: International Maritime Organization number
        - name: vessel_name
          in: query
          schema:
            type: string
        - name: protocol
          in: query
          schema:
            type: string
            enum: [jsono, xml]
            default: jsono
        - name: msgtype
          in: query
          schema:
            type: string
            enum: [simple, extended]
            default: simple
      responses:
        '200':
          description: Vessel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VesselResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /exportvesseltrack/{apikey}:
    get:
      operationId: getVesselTrack
      summary: Get vessel position track
      description: >-
        Retrieve the position history (track) of a vessel over a specified
        time period. Returns a sequence of AIS position reports.
      tags:
        - Vessel Tracking
      parameters:
        - name: apikey
          in: path
          required: true
          schema:
            type: string
        - name: v
          in: query
          schema:
            type: integer
            default: 1
        - name: MMSI
          in: query
          required: true
          schema:
            type: string
        - name: fromdate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Track start time (UTC, ISO 8601)
        - name: todate
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Track end time (UTC, ISO 8601)
        - name: protocol
          in: query
          schema:
            type: string
            enum: [jsono, xml, csv]
            default: jsono
      responses:
        '200':
          description: Vessel position track
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VesselTrackResponse'
  /getexpectedarrivals/{apikey}:
    get:
      operationId: getExpectedArrivals
      summary: Get expected vessel arrivals at a port
      description: >-
        Retrieve vessels expected to arrive at a specific port based on
        voyage destination data and ETA information from AIS messages.
      tags:
        - Port Operations
      parameters:
        - name: apikey
          in: path
          required: true
          schema:
            type: string
        - name: portid
          in: query
          required: true
          schema:
            type: integer
          description: MarineTraffic port identifier
        - name: v
          in: query
          schema:
            type: integer
            default: 1
        - name: fromdate
          in: query
          schema:
            type: string
            format: date-time
        - name: todate
          in: query
          schema:
            type: string
            format: date-time
        - name: protocol
          in: query
          schema:
            type: string
            enum: [jsono, xml]
            default: jsono
      responses:
        '200':
          description: Expected arrivals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpectedArrivalsResponse'
  /getportcalls/{apikey}:
    get:
      operationId: getPortCalls
      summary: Get port call events
      description: >-
        Retrieve historical and live port call events (arrivals, departures)
        for a port or vessel within a given time range.
      tags:
        - Port Operations
      parameters:
        - name: apikey
          in: path
          required: true
          schema:
            type: string
        - name: portid
          in: query
          schema:
            type: integer
        - name: MMSI
          in: query
          schema:
            type: string
        - name: fromdate
          in: query
          schema:
            type: string
            format: date-time
        - name: todate
          in: query
          schema:
            type: string
            format: date-time
        - name: v
          in: query
          schema:
            type: integer
            default: 1
        - name: protocol
          in: query
          schema:
            type: string
            enum: [jsono, xml]
            default: jsono
      responses:
        '200':
          description: Port call events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortCallsResponse'
  /getvesselpositions/{apikey}:
    get:
      operationId: getVesselPositions
      summary: Get vessel positions in area
      description: >-
        Retrieve real-time positions of all vessels currently within a
        specified geographic bounding box.
      tags:
        - Vessel Tracking
      parameters:
        - name: apikey
          in: path
          required: true
          schema:
            type: string
        - name: MINLAT
          in: query
          required: true
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
        - name: MAXLAT
          in: query
          required: true
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
        - name: MINLON
          in: query
          required: true
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
        - name: MAXLON
          in: query
          required: true
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
        - name: SHIPTYPE
          in: query
          schema:
            type: integer
          description: AIS vessel type code filter
        - name: v
          in: query
          schema:
            type: integer
            default: 8
        - name: protocol
          in: query
          schema:
            type: string
            enum: [jsono, xml, csv]
            default: jsono
      responses:
        '200':
          description: Vessel positions in area
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VesselPositionsResponse'
components:
  securitySchemes:
    APIKey:
      type: apiKey
      in: query
      name: apikey
      description: MarineTraffic API key provided in the URL path for most endpoints
  responses:
    Unauthorized:
      description: Invalid API key or subscription does not include this service
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: API credits exhausted or rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Vessel:
      type: object
      description: Vessel static and voyage data
      properties:
        MMSI:
          type: string
          description: Maritime Mobile Service Identity
          pattern: '^[0-9]{9}$'
        IMO:
          type: integer
          description: International Maritime Organization number
        SHIP_ID:
          type: integer
          description: MarineTraffic internal vessel ID
        LAT:
          type: number
          format: double
          description: Last known latitude (WGS84)
        LON:
          type: number
          format: double
          description: Last known longitude (WGS84)
        SPEED:
          type: number
          description: Speed over ground in knots (× 10)
        HEADING:
          type: integer
          description: True heading in degrees (0-359)
        COURSE:
          type: number
          description: Course over ground in degrees
        STATUS:
          type: integer
          description: AIS navigational status code
        TIMESTAMP:
          type: string
          format: date-time
          description: UTC timestamp of last position report
        DSRC:
          type: string
          enum: [TER, SAT]
          description: Data source - terrestrial or satellite AIS
        VESSEL_NAME:
          type: string
        CALLSIGN:
          type: string
        FLAG:
          type: string
          description: ISO 3166-1 alpha-2 flag state code
        SHIPTYPE:
          type: integer
          description: AIS vessel type code
        CARGO:
          type: integer
          description: Cargo type code
        CURRENT_PORT:
          type: string
        LAST_PORT:
          type: string
        NEXT_PORT_NAME:
          type: string
        ETA:
          type: string
          format: date-time
          description: Estimated time of arrival at destination
        DESTINATION:
          type: string
        LENGTH:
          type: integer
          description: Vessel length in meters
        WIDTH:
          type: integer
          description: Vessel beam/width in meters
        DRAUGHT:
          type: number
          description: Current draught in meters
        GT:
          type: integer
          description: Gross tonnage
        DWT:
          type: integer
          description: Deadweight tonnage
        YEAR_BUILT:
          type: integer
    VesselResponse:
      type: object
      properties:
        DATA:
          type: array
          items:
            $ref: '#/components/schemas/Vessel'
    VesselTrackPoint:
      type: object
      properties:
        MMSI:
          type: string
        LAT:
          type: number
          format: double
        LON:
          type: number
          format: double
        SPEED:
          type: number
        HEADING:
          type: integer
        COURSE:
          type: number
        STATUS:
          type: integer
        TIMESTAMP:
          type: string
          format: date-time
    VesselTrackResponse:
      type: object
      properties:
        DATA:
          type: array
          items:
            $ref: '#/components/schemas/VesselTrackPoint'
    PortCall:
      type: object
      properties:
        PORTCALL_ID:
          type: integer
        MMSI:
          type: string
        SHIP_ID:
          type: integer
        VESSEL_NAME:
          type: string
        PORT_ID:
          type: integer
        PORT_NAME:
          type: string
        UNLOCODE:
          type: string
          description: UN/LOCODE port identifier
        ARRIVAL:
          type: string
          format: date-time
        DEPARTURE:
          type: string
          format: date-time
        DURATION_HOURS:
          type: number
        MAX_DRAUGHT:
          type: number
    PortCallsResponse:
      type: object
      properties:
        DATA:
          type: array
          items:
            $ref: '#/components/schemas/PortCall'
    ExpectedArrival:
      type: object
      properties:
        MMSI:
          type: string
        VESSEL_NAME:
          type: string
        SHIP_ID:
          type: integer
        PORT_ID:
          type: integer
        PORT_NAME:
          type: string
        EXPECTED_ARRIVAL:
          type: string
          format: date-time
        CURRENT_LAT:
          type: number
        CURRENT_LON:
          type: number
        DISTANCE_REMAINING:
          type: number
          description: Distance to port in nautical miles
    ExpectedArrivalsResponse:
      type: object
      properties:
        DATA:
          type: array
          items:
            $ref: '#/components/schemas/ExpectedArrival'
    VesselPositionsResponse:
      type: object
      properties:
        DATA:
          type: array
          items:
            $ref: '#/components/schemas/Vessel'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: integer
              description:
                type: string
tags:
  - name: Port Operations
    description: Port calls, arrivals, and departures
  - name: Vessel Tracking
    description: Real-time and historical vessel positions
  - name: Vessels
    description: Vessel static data and characteristics