openapi: 3.0.3
info:
  title: MyShipTracking Account Ports API
  description: 'The MyShipTracking API delivers real-time terrestrial-AIS maritime data over REST. It exposes live vessel positions and voyage data, static vessel particulars, vessels within a geographic zone or near a reference ship, historical tracks, port details, port calls, and estimated arrivals, plus fleet management. Every response is returned in a standardized envelope (status, duration, timestamp, and either data on success or code/message on error), in JSON by default or XML via the Accept header.


    Authentication: pass your API key as either `Authorization: Bearer YOUR_API_KEY` or the `x-api-key` header on every request.


    Billing: calls are metered in credits. Simple responses cost 1 credit, extended responses 3 credits, and history/port-call queries 5 credits per distinct date. No credits are charged when a request returns no results, and a single request is capped at 500 credits.


    Scope note: the paths and parameters below for /vessel, /vessel/zone, /vessel/nearby, /vessel/track, /vessel/search, /port, /port/estimate, /port/calls, and /account/info were confirmed from MyShipTracking''s own per-endpoint documentation. The /vessel/bulk path is inferred from the Bulk Vessel Retrieval documentation and should be verified. Response schemas are modeled from the documented field lists; additional Fleet, Port Search, and Vessels In Port endpoints exist in the API but are not modeled here.'
  version: '2.0'
  contact:
    name: MyShipTracking
    url: https://www.myshiptracking.com
  termsOfService: https://api.myshiptracking.com/docs/terms
servers:
- url: https://api.myshiptracking.com/api/v2
  description: MyShipTracking API v2
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Ports
  description: Port details, port calls, and arrival estimates.
paths:
  /port:
    get:
      operationId: getPortDetails
      tags:
      - Ports
      summary: Port details
      description: Retrieve details for a specific port. Provide exactly one of port_id or unloco. 1 credit per request.
      parameters:
      - name: port_id
        in: query
        required: false
        description: Unique port identifier. Provide exactly one of port_id or unloco.
        schema:
          type: integer
      - name: unloco
        in: query
        required: false
        description: UN/LOCODE of the port. Provide exactly one of port_id or unloco.
        schema:
          type: string
      responses:
        '200':
          description: Port details envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /port/estimate:
    get:
      operationId: getPortEstimate
      tags:
      - Ports
      summary: Port estimated arrivals (ETA)
      description: Obtain estimated arrival times for vessels heading to a given port. Provide exactly one of port_id or unloco. 1 credit per record returned.
      parameters:
      - name: port_id
        in: query
        required: false
        description: Port identifier. Provide exactly one of port_id or unloco.
        schema:
          type: integer
      - name: unloco
        in: query
        required: false
        description: Port UN/LOCODE. Provide exactly one of port_id or unloco.
        schema:
          type: string
      responses:
        '200':
          description: Estimated arrivals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortEstimateEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /port/calls:
    get:
      operationId: getPortCalls
      tags:
      - Ports
      summary: Port calls (arrivals and departures)
      description: Retrieve historical port call events. Supply at least one of mmsi, or port_id/unloco, and either days or a fromdate/todate range (not both). Charged 5 credits per distinct date in the returned records.
      parameters:
      - name: type
        in: query
        required: false
        description: 'Filter: 0 all, 1 arrivals, 2 departures.'
        schema:
          type: integer
          enum:
          - 0
          - 1
          - 2
          default: 0
      - name: port_id
        in: query
        required: false
        description: Port identifier (mutually exclusive with unloco).
        schema:
          type: integer
      - name: unloco
        in: query
        required: false
        description: Port UN/LOCODE (mutually exclusive with port_id).
        schema:
          type: string
      - name: mmsi
        in: query
        required: false
        description: 9-digit vessel identifier.
        schema:
          type: integer
      - name: days
        in: query
        required: false
        description: Lookback period in days. Provide either days OR fromdate/todate.
        schema:
          type: integer
      - name: fromdate
        in: query
        required: false
        description: Start datetime in UTC (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: todate
        in: query
        required: false
        description: End datetime in UTC (ISO 8601).
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Port call events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortCallsEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    BadRequest:
      description: Parameter validation failed or an invalid identifier was supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    ErrorEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeMeta'
      - type: object
        properties:
          code:
            type: string
            example: MST_ERR_VALIDATOR
          message:
            type: string
    PortEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeMeta'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/Port'
    EnvelopeMeta:
      type: object
      properties:
        status:
          type: string
          example: success
        duration:
          type: string
          description: Processing time.
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 server timestamp.
    Port:
      type: object
      properties:
        port_id:
          type: integer
        name:
          type: string
        unloco:
          type: string
        port_type:
          type: string
        country:
          type: string
        timezone:
          type: string
    PortEstimateEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeMeta'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/PortEstimate'
    PortEstimate:
      type: object
      properties:
        mmsi:
          type: integer
        imo:
          type: integer
        vessel_name:
          type: string
        vtype:
          type: integer
        vessel_type:
          type: string
        flag:
          type: string
        gt:
          type: integer
        dwt:
          type: integer
        built:
          type: integer
        length:
          type: integer
        width:
          type: integer
        eta_utc:
          type: string
          format: date-time
        eta_local:
          type: string
          format: date-time
    PortCall:
      type: object
      properties:
        event:
          type: string
          enum:
          - ARRIVAL
          - DEPARTURE
        time_utc:
          type: string
          format: date-time
        time_local:
          type: string
          format: date-time
        mmsi:
          type: integer
        imo:
          type: integer
        vessel_name:
          type: string
        port_id:
          type: integer
        port_name:
          type: string
        unloco:
          type: string
    PortCallsEnvelope:
      allOf:
      - $ref: '#/components/schemas/EnvelopeMeta'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/PortCall'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed as: Authorization: Bearer YOUR_API_KEY.'
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key passed in the x-api-key header.