VesselFinder Containers API

openapi: 3.2.0
info:
  title: VesselFinder Container Tracking Containers API
  description: 'Container Tracking API for ocean freight monitoring. Supplies real-time vessel position

    overlaid on container schedules — origin, destination, transhipments, ports of loading

    and discharge, and event timestamps. Lookups are by container number (11 characters,

    four letters + seven digits) and optional carrier SCAC code; if SCAC is omitted the API

    auto-detects the line. Successful container lookups are cached for 12 hours; the first

    lookup per container deducts one unit from the subscription, subsequent lookups within

    30 days are free.

    '
  version: '1.0'
  contact:
    name: VesselFinder Container Tracking Support
    url: https://container.vesselfinder.com/api/1.0/docs
  license:
    name: Commercial — VesselFinder Terms of Use
    url: https://www.vesselfinder.com/terms
servers:
- url: https://container.vesselfinder.com/api/1.0
  description: VesselFinder Container Tracking API
security:
- PathApiKey: []
tags:
- name: Containers
  description: Real-time container track-and-trace.
paths:
  /container/{apiKey}/{containerNumber}/{sealine}:
    get:
      tags:
      - Containers
      summary: Track Container
      description: 'Look up the shipment for the specified container. Returns container origin,

        destination, current vessel position, progress, and schedule events. May respond

        with 202 Accepted while the request is processing — clients should poll the same

        URL no faster than every 60 seconds. Typical processing time is under one minute

        and may extend up to 15–20 minutes in worst case.

        '
      operationId: trackContainer
      parameters:
      - name: apiKey
        in: path
        required: true
        description: Personal API key for the Container Tracking service.
        schema:
          type: string
      - name: containerNumber
        in: path
        required: true
        description: 11-character container number (four letters + seven digits).
        schema:
          type: string
          pattern: ^[A-Z]{4}[0-9]{7}$
          example: MEDU6965343
      - name: sealine
        in: path
        required: true
        description: '4-character carrier SCAC code (e.g. `MSCU`). Use `AUTO` to let the service

          auto-detect the carrier.

          '
        schema:
          type: string
          default: AUTO
          example: MSCU
      responses:
        '200':
          description: Container shipment data is ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerShipment'
        '202':
          description: Request queued or still processing — retry after 60 seconds or longer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '400':
          description: Invalid container number, SCAC, or rate limit exceeded.
        '401':
          description: Invalid or expired API key.
        '402':
          description: Container subscription limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionError'
        '409':
          description: Carrier-related error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierError'
components:
  schemas:
    ContainerShipment:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - queued
          - processing
          - error
        general:
          $ref: '#/components/schemas/General'
        schedule:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleEntry'
        vessel:
          $ref: '#/components/schemas/Vessel'
    ScheduleEntry:
      type: object
      properties:
        port:
          type: string
        locode:
          type: string
        event:
          type: string
          description: Event code (CEP, CPS, CGI, CLL, VDL, VAT, CDT, CLT, VDT, VAD, CDD, CGO, CDC, CER, UNK).
        timestamp:
          type: string
          format: date-time
        actual:
          type: boolean
          description: True if the timestamp is observed; false if scheduled.
        vessel:
          $ref: '#/components/schemas/Vessel'
    CarrierError:
      type: object
      properties:
        status:
          type: string
        code:
          type: string
        message:
          type: string
    QueuedResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - queued
          - processing
        retryAfter:
          type: integer
          description: Suggested retry interval in seconds.
    General:
      type: object
      properties:
        origin:
          type: string
        destination:
          type: string
        progress:
          type: number
          description: 0..100 percent.
        currentLocation:
          type: string
        carrier:
          type: string
        sealine:
          type: string
          description: SCAC code of the carrier.
    Vessel:
      type: object
      properties:
        name:
          type: string
        imo:
          type: integer
        mmsi:
          type: integer
        latitude:
          type: number
        longitude:
          type: number
        speed:
          type: number
        course:
          type: number
    SubscriptionError:
      type: object
      properties:
        status:
          type: string
        subscription:
          type: object
          properties:
            remaining:
              type: integer
            expirationDate:
              type: string
              format: date-time
  securitySchemes:
    PathApiKey:
      type: apiKey
      in: query
      name: apiKey
      description: 'API key is passed as a path segment of the tracking URL, not as a header or query

        parameter. This security scheme is declarative only.

        '