cruise-itinerary-com Ships and ports API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data Ships and ports API
  version: 1.0.0
  summary: Cruise reference data, weekly fares, itineraries on the calendar, port traffic and a change feed.
  description: 'Reference data and weekly fare snapshots for cruise lines, ships, ports and sailings, refreshed every Monday. Fares are snapshots from an inventory feed, not live bookable prices. A null fare means the cabin is not offered or is sold out; the feed does not distinguish.


    **Authentication.** Send `Authorization: Bearer ` or `X-API-Key: `. Every endpoint needs a key, and a Free key costs nothing but an email address. A request without one gets 401 `key_required`. A malformed, unknown or revoked key is a 401, never a silent downgrade.


    **Plans.** Each endpoint lists the lowest plan that can call it in `x-required-plan`. Rate limits are per minute and some plans have a monthly call quota; both are reported in response headers. See /pricing for the current numbers.


    **Envelope.** Single objects come back as `{"data": {...}, "meta": {...}}`, lists as `{"data": [...], "meta": {as_of, page, per_page, total, has_more}}`, errors as `{"error": {status, code, message}}`. Every key is always present; absent values are null. Dates are YYYY-MM-DD. Money is whole US dollars.


    **Ids.** Lines, ships, ports, destinations, regions and cruises use slugs. Sailings use their integer id.


    **Caching.** Anonymous responses from open endpoints are cacheable for an hour and carry an ETag. Everything keyed is `private, no-store`.


    **Counting.** A keyed request that returns 2xx counts toward the monthly quota; errors do not.'
  termsOfService: https://cruise-itinerary.com/terms
  contact:
    name: Cruise Itinerary
    url: https://cruise-itinerary.com
servers:
- url: https://cruise-itinerary.com
  description: Production
security:
- {}
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Ships and ports
paths:
  /v1/ships/{id}/schedule:
    get:
      tags:
      - Ships and ports
      summary: Ship schedule
      description: 'Where a ship is on each day: one row per stop, with sea days. When sailings overlap, the shortest one that covers a day owns it. Window limit: 400 days; default 90 days from today.'
      operationId: getShipSchedule
      x-required-plan: developer
      parameters:
      - name: id
        in: path
        required: true
        description: Ship slug.
        schema:
          type: string
        example: eurodam
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: from
        in: query
        required: false
        description: First day (default today).
        schema:
          type: string
          format: date
        example: '2026-10-03'
      - name: to
        in: query
        required: false
        description: Last day.
        schema:
          type: string
          format: date
        example: '2026-10-31'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ShipDay'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - date: '2026-10-24'
                  seq: 0
                  kind: embark
                  port:
                    id: ft-lauderdale
                    name: Ft. Lauderdale
                    latitude: 26.1223084
                    longitude: -80.1433786
                  day_confidence: exact
                  sailing_id: 14039046
                - date: '2026-10-25'
                  seq: 0
                  kind: call
                  port:
                    id: half-moon-cay
                    name: Half Moon Cay
                    latitude: 24.5770527
                    longitude: -75.9232579
                  day_confidence: exact
                  sailing_id: 14039046
                - date: '2026-10-26'
                  seq: 0
                  kind: sea
                  port: null
                  day_confidence: exact
                  sailing_id: 14039046
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 3
                  total: 8
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/ports/{id}/calendar:
    get:
      tags:
      - Ships and ports
      summary: Port traffic calendar
      description: 'Ships, lower berths and turnarounds per day. Only days with at least one ship appear; a missing day has none. Window limit: 730 days; default 90 days from today. Berths count lower-berth capacity; real headcount runs 10 to 20 percent higher.'
      operationId: getPortCalendar
      x-required-plan: business
      parameters:
      - name: id
        in: path
        required: true
        description: Port slug (or merged legacy id).
        schema:
          type: string
        example: miami
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: from
        in: query
        required: false
        description: First day (default today).
        schema:
          type: string
          format: date
        example: '2026-11-01'
      - name: to
        in: query
        required: false
        description: Last day.
        schema:
          type: string
          format: date
        example: '2026-11-30'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortDay'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - date: '2026-11-01'
                  ships: 7
                  berths: 26885
                  ships_no_capacity: 0
                  embark_ships: 5
                  disembark_ships: 7
                  turnaround_ships: 5
                  estimated_ships: 0
                  busy_pct: 86
                - date: '2026-11-02'
                  ships: 3
                  berths: 12560
                  ships_no_capacity: 0
                  embark_ships: 3
                  disembark_ships: 3
                  turnaround_ships: 3
                  estimated_ships: 0
                  busy_pct: 39
                - date: '2026-11-05'
                  ships: 4
                  berths: 11456
                  ships_no_capacity: 0
                  embark_ships: 4
                  disembark_ships: 4
                  turnaround_ships: 4
                  estimated_ships: 0
                  busy_pct: 30
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 3
                  total: 27
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/ports/{id}/days/{date}:
    get:
      tags:
      - Ships and ports
      summary: Port day detail
      description: The counts for one day plus the ships behind them. A day with no ships returns zero counts and an empty `calls` list.
      operationId: getPortDay
      x-required-plan: business
      parameters:
      - name: id
        in: path
        required: true
        description: Port slug (or merged legacy id).
        schema:
          type: string
        example: miami
      - name: date
        in: path
        required: true
        description: YYYY-MM-DD.
        schema:
          type: string
        example: '2026-11-14'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/PortDayDetail'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  date: '2026-11-14'
                  ships: 7
                  berths: 27493
                  ships_no_capacity: 0
                  embark_ships: 7
                  disembark_ships: 7
                  turnaround_ships: 7
                  estimated_ships: 0
                  busy_pct: 88
                  calls:
                  - ship:
                      id: carnival-magic
                      name: Carnival Magic
                      passengers: 3690
                    line:
                      id: carnival-cruise-line
                      name: Carnival Cruise Line
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14252373
                  - ship:
                      id: carnival-sunrise
                      name: Carnival Sunrise
                      passengers: 2984
                    line:
                      id: carnival-cruise-line
                      name: Carnival Cruise Line
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14252960
                  - ship:
                      id: msc-world-america
                      name: MSC World America
                      passengers: 5240
                    line:
                      id: msc-cruises
                      name: MSC Cruises
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14290891
                  - ship:
                      id: norwegian-luna
                      name: Norwegian Luna
                      passengers: 3565
                    line:
                      id: norwegian-cruise-line
                      name: Norwegian Cruise Line
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14221900
                  - ship:
                      id: freedom-of-the-seas
                      name: Freedom of the Seas
                      passengers: 3634
                    line:
                      id: royal-caribbean
                      name: Royal Caribbean
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14240653
                  - ship:
                      id: icon-of-the-seas
                      name: Icon of the Seas
                      passengers: 5610
                    line:
                      id: royal-caribbean
                      name: Royal Caribbean
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14089008
                  - ship:
                      id: scarlet-lady
                      name: Scarlet Lady
                      passengers: 2770
                    line:
                      id: virgin-voyages
                      name: Virgin Voyages
                    kind: turnaround
                    day_confidence: exact
                    sailing_id: 14199956
                meta:
                  as_of: '2026-10-19'
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
components:
  responses:
    E429:
      description: Per-minute rate limit (`rate_limited`, with `Retry-After`) or monthly quota (`quota_exceeded`) reached.
      headers:
        Retry-After:
          description: Seconds until the rate window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 429
              code: rate_limited
              message: Rate limit of 60 requests per minute exceeded. Retry in 31 seconds.
    E401:
      description: No key was sent (`key_required`; a free key is one email away at /signup), or the key is malformed, unknown or revoked (`invalid_key`). A bad key is never treated as anonymous.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 401
              code: key_required
              message: 'This endpoint needs an API key. Get a free one at https://cruise-itinerary.com/signup and send it as "Authorization: Bearer <key>".'
              required_plan: free
    E403:
      description: The plan does not include this endpoint (`plan_required`, with `required_plan`), or the account is suspended (`account_suspended`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 403
              code: plan_required
              message: This endpoint needs the Business plan or above; this key is on the Developer plan.
              required_plan: business
    E400:
      description: 'Bad request: an unknown or malformed parameter. The message names it.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 400
              code: bad_request
              message: 'Parameter ''cabin'' must be one of: inside, outside, balcony, suite.'
    E500:
      description: Internal error. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 500
              code: internal
              message: Internal error. Try again; if it persists, contact support.
    E404:
      description: No such entity or endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 404
              code: not_found
              message: No such ship.
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per one-minute window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - status
          - code
          - message
          properties:
            status:
              type: integer
            code:
              type: string
              enum:
              - bad_request
              - key_required
              - invalid_key
              - account_suspended
              - plan_required
              - not_found
              - rate_limited
              - quota_exceeded
              - method_not_allowed
              - internal
            message:
              type: string
              description: Human-readable explanation; safe to show to a developer, not a stable string to match on.
            required_plan:
              type: string
              description: 'Present on plan_required and key_required: the lowest plan that can call the endpoint.'
              enum:
              - free
              - developer
              - business
              - platform
    ListMeta:
      type: object
      properties:
        as_of:
          oneOf:
          - type: string
            description: Date of the latest inventory load the response reflects.
            format: date
          - type: 'null'
        page:
          type: integer
          description: Current page, from 1.
        per_page:
          type: integer
          description: Rows per page.
        total:
          type: integer
          description: Rows matching the query across all pages.
        has_more:
          type: boolean
          description: True when a later page exists.
      required:
      - as_of
      - page
      - per_page
      - total
      - has_more
      additionalProperties: false
    PortPoint:
      oneOf:
      - type: object
        properties:
          id:
            type: string
          name:
            type: string
          latitude:
            oneOf:
            - type: number
            - type: 'null'
          longitude:
            oneOf:
            - type: number
            - type: 'null'
        required:
        - id
        - name
        - latitude
        - longitude
        additionalProperties: false
      - type: 'null'
    Ref:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
      required:
      - id
      - name
      additionalProperties: false
    PortDay:
      type: object
      properties:
        date:
          type: string
          format: date
        ships:
          type: integer
          description: Distinct ships in port.
        berths:
          type: integer
          description: Sum of known lower-berth capacity.
        ships_no_capacity:
          type: integer
          description: Ships counted whose capacity is unknown.
        embark_ships:
          type: integer
          description: Includes turnarounds.
        disembark_ships:
          type: integer
          description: Includes turnarounds.
        turnaround_ships:
          type: integer
          description: Ships that disembark one sailing and embark the next the same day.
        estimated_ships:
          type: integer
          description: Ships whose day here is estimated rather than exact.
        busy_pct:
          oneOf:
          - type: integer
            description: Percentile among this port's busy days within a year either side. 100 is the busiest.
          - type: 'null'
      required:
      - date
      - ships
      - berths
      - ships_no_capacity
      - embark_ships
      - disembark_ships
      - turnaround_ships
      - estimated_ships
      - busy_pct
      additionalProperties: false
    PortDayDetail:
      type: object
      properties:
        date:
          type: string
          format: date
        ships:
          type: integer
          description: Distinct ships in port.
        berths:
          type: integer
          description: Sum of known lower-berth capacity.
        ships_no_capacity:
          type: integer
          description: Ships counted whose capacity is unknown.
        embark_ships:
          type: integer
          description: Includes turnarounds.
        disembark_ships:
          type: integer
          description: Includes turnarounds.
        turnaround_ships:
          type: integer
          description: Ships that disembark one sailing and embark the next the same day.
        estimated_ships:
          type: integer
          description: Ships whose day here is estimated rather than exact.
        busy_pct:
          oneOf:
          - type: integer
            description: Percentile among this port's busy days within a year either side. 100 is the busiest.
          - type: 'null'
        calls:
          type: array
          items:
            type: object
            properties:
              ship:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  passengers:
                    oneOf:
                    - type: integer
                    - type: 'null'
                required:
                - id
                - name
                - passengers
                additionalProperties: false
              line:
                oneOf:
                - $ref: '#/components/schemas/Ref'
                - type: 'null'
              kind:
                type: string
                enum:
                - embark
                - call
                - scenic
                - disembark
                - turnaround
              day_confidence:
                type: string
                enum:
                - exact
                - estimated
              sailing_id:
                type: integer
            required:
            - ship
            - line
            - kind
            - day_confidence
            - sailing_id
            additionalProperties: false
      required:
      - date
      - ships
      - berths
      - ships_no_capacity
      - embark_ships
      - disembark_ships
      - turnaround_ships
      - estimated_ships
      - busy_pct
      - calls
      additionalProperties: false
      description: The ships behind the counts. Named calls, not ships, because ships is already the count.
    Meta:
      type: object
      properties:
        as_of:
          oneOf:
          - type: string
            description: Date of the latest inventory load the response reflects.
            format: date
          - type: 'null'
      required:
      - as_of
      additionalProperties: false
    ShipDay:
      type: object
      properties:
        date:
          type: string
          format: date
        seq:
          type: integer
          description: Order within the day.
        kind:
          type: string
          enum:
          - embark
          - call
          - scenic
          - transit
          - sea
          - disembark
          - turnaround
        port:
          $ref: '#/components/schemas/PortPoint'
        day_confidence:
          type: string
          enum:
          - exact
          - estimated
        sailing_id:
          type: integer
          description: The sailing that owns this day.
      required:
      - date
      - seq
      - kind
      - port
      - day_confidence
      - sailing_id
      additionalProperties: false
  parameters:
    page:
      name: page
      in: query
      description: Page number, from 1. Pages deeper than 100,000 rows are refused.
      schema:
        type: integer
        minimum: 1
        default: 1
    per_page:
      name: per_page
      in: query
      description: Rows per page, 1 to 200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Key from the dashboard: ci_live_ followed by 32 letters and digits.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same key, as a header.