cruise-itinerary-com Reference data API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data Reference data 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: Reference data
paths:
  /v1/lines:
    get:
      tags:
      - Reference data
      summary: List cruise lines
      description: Every cruise line, alphabetical, with how many ships and upcoming sailings each has.
      operationId: listLines
      x-required-plan: free
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      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/Line'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - id: amawaterways
                  name: AmaWaterways
                  ship_count: 41
                  sailing_count: 3478
                - id: american-cruise-lines
                  name: American Cruise Lines
                  ship_count: 23
                  sailing_count: 690
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 45
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/lines/{id}:
    get:
      tags:
      - Reference data
      summary: Get a cruise line
      description: One line by slug.
      operationId: getLine
      x-required-plan: free
      parameters:
      - name: id
        in: path
        required: true
        description: Line slug.
        schema:
          type: string
        example: holland-america-line
      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/Line'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  id: holland-america-line
                  name: Holland America Line
                  ship_count: 13
                  sailing_count: 1215
                meta:
                  as_of: '2026-10-19'
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/ships:
    get:
      tags:
      - Reference data
      summary: List ships
      description: Ships, alphabetical. `q` matches part of the name or an exact IMO number.
      operationId: listShips
      x-required-plan: free
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: line
        in: query
        required: false
        description: Only ships of this line (slug).
        schema:
          type: string
        example: holland-america-line
      - name: q
        in: query
        required: false
        description: Name contains, or exact IMO.
        schema:
          type: string
        example: eurodam
      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/Ship'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - id: eurodam
                  name: Eurodam
                  line:
                    id: holland-america-line
                    name: Holland America Line
                  imo: '9378448'
                  mmsi: '245206000'
                  passengers: 2104
                  crew: 929
                  gross_tonnage: 86273
                  decks: 11
                  length_ft: 936
                  width_ft: 106
                  maiden_voyage: '2008-07-05'
                  launched: '2008-01-01'
                  refurbished: null
                  adults_only: false
                - id: koningsdam
                  name: Koningsdam
                  line:
                    id: holland-america-line
                    name: Holland America Line
                  imo: '9692557'
                  mmsi: '244830547'
                  passengers: 2650
                  crew: 1025
                  gross_tonnage: 99500
                  decks: 12
                  length_ft: 935
                  width_ft: 115
                  maiden_voyage: '2016-04-04'
                  launched: null
                  refurbished: null
                  adults_only: false
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 13
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/ships/{id}:
    get:
      tags:
      - Reference data
      summary: Get a ship
      description: One ship by slug.
      operationId: getShip
      x-required-plan: free
      parameters:
      - name: id
        in: path
        required: true
        description: Ship slug.
        schema:
          type: string
        example: eurodam
      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/Ship'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  id: eurodam
                  name: Eurodam
                  line:
                    id: holland-america-line
                    name: Holland America Line
                  imo: '9378448'
                  mmsi: '245206000'
                  passengers: 2104
                  crew: 929
                  gross_tonnage: 86273
                  decks: 11
                  length_ft: 936
                  width_ft: 106
                  maiden_voyage: '2008-07-05'
                  launched: '2008-01-01'
                  refurbished: null
                  adults_only: false
                meta:
                  as_of: '2026-10-19'
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/ports:
    get:
      tags:
      - Reference data
      summary: List ports
      description: Ports and scenic stops. Use `has_calls=true` for ports a ship is scheduled to visit. For matching free text to a port, use `/v1/resolve`.
      operationId: listPorts
      x-required-plan: free
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: q
        in: query
        required: false
        description: Name or alias contains.
        schema:
          type: string
        example: miami
      - name: destination
        in: query
        required: false
        description: Destination slug.
        schema:
          type: string
        example: miami
      - name: region
        in: query
        required: false
        description: Region slug.
        schema:
          type: string
        example: caribbean
      - name: has_calls
        in: query
        required: false
        description: 'true: only ports with scheduled calls; false: only those without.'
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: kind
        in: query
        required: false
        description: port, scenic or transit.
        schema:
          type: string
          enum:
          - port
          - scenic
          - transit
      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/Port'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - id: miami
                  name: Miami
                  kind: port
                  latitude: 25.7741566
                  longitude: -80.1935973
                  destination:
                    id: miami
                    name: Miami
                  region:
                    id: united-states
                    name: United States
                  aliases: []
                  upcoming_calls: 2377
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 1
                  has_more: false
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/ports/{id}:
    get:
      tags:
      - Reference data
      summary: Get a port
      description: One port by slug. The numeric id of a port that was merged into another also works and returns the surviving port, with `meta.resolved_from` set to the id you sent.
      operationId: getPort
      x-required-plan: free
      parameters:
      - name: id
        in: path
        required: true
        description: Port slug, or the numeric id of a merged legacy port.
        schema:
          type: string
        example: miami
      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/Port'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  id: miami
                  name: Miami
                  kind: port
                  latitude: 25.7741566
                  longitude: -80.1935973
                  destination:
                    id: miami
                    name: Miami
                  region:
                    id: united-states
                    name: United States
                  aliases: []
                  upcoming_calls: 2377
                meta:
                  as_of: '2026-10-19'
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/destinations:
    get:
      tags:
      - Reference data
      summary: List destinations
      description: Destinations with their region and a representative coordinate.
      operationId: listDestinations
      x-required-plan: free
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      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/Destination'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - id: abu-dhabi
                  name: Abu Dhabi
                  region:
                    id: middle-east
                    name: Middle East
                  latitude: 24.453884
                  longitude: 54.3773438
                - id: acapulco
                  name: Acapulco
                  region:
                    id: mexico-region
                    name: Mexico region
                  latitude: 16.863611
                  longitude: -99.8825
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 379
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '404':
          $ref: '#/components/responses/E404'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/regions:
    get:
      tags:
      - Reference data
      summary: List regions
      description: The 18 top-level regions.
      operationId: listRegions
      x-required-plan: free
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      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/Region'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - id: africa
                  name: Africa
                - id: alaska-region
                  name: Alaska region
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 2
                  total: 18
                  has_more: true
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '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
    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.
  schemas:
    Ship:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
        line:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        imo:
          oneOf:
          - type: string
            description: IMO number, 7 digits.
          - type: 'null'
        mmsi:
          oneOf:
          - type: string
            description: MMSI, 9 digits.
          - type: 'null'
        passengers:
          oneOf:
          - type: integer
            description: Lower-berth capacity. Real headcount runs 10 to 20 percent higher.
          - type: 'null'
        crew:
          oneOf:
          - type: integer
          - type: 'null'
        gross_tonnage:
          oneOf:
          - type: integer
          - type: 'null'
        decks:
          oneOf:
          - type: integer
          - type: 'null'
        length_ft:
          oneOf:
          - type: number
          - type: 'null'
        width_ft:
          oneOf:
          - type: number
          - type: 'null'
        maiden_voyage:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        launched:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        refurbished:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        adults_only:
          oneOf:
          - type: boolean
          - type: 'null'
      required:
      - id
      - name
      - line
      - imo
      - mmsi
      - passengers
      - crew
      - gross_tonnage
      - decks
      - length_ft
      - width_ft
      - maiden_voyage
      - launched
      - refurbished
      - adults_only
      additionalProperties: false
    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
    Port:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
        kind:
          type: string
          description: scenic marks a stretch of cruising the feed lists as a stop, such as a glacier; transit marks a travel leg or unnamed stop (a train, a transfer, Captain's Choice). Neither is a port call.
          enum:
          - port
          - scenic
          - transit
        latitude:
          oneOf:
          - type: number
          - type: 'null'
        longitude:
          oneOf:
          - type: number
          - type: 'null'
        destination:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        region:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        aliases:
          type: array
          items:
            type: string
        upcoming_calls:
          type: integer
          description: Future days on which a ship is scheduled at this port.
      required:
      - id
      - name
      - kind
      - latitude
      - longitude
      - destination
      - region
      - aliases
      - upcoming_calls
      additionalProperties: false
    Destination:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        region:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        latitude:
          oneOf:
          - type: number
          - type: 'null'
        longitude:
          oneOf:
          - type: number
          - type: 'null'
      required:
      - id
      - name
      - region
      - latitude
      - longitude
      additionalProperties: false
    Line:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
        ship_count:
          type: integer
        sailing_count:
          type: integer
          description: Upcoming sailings.
      required:
      - id
      - name
      - ship_count
      - sailing_count
      additionalProperties: false
    Ref:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
      required:
      - id
      - name
      additionalProperties: false
    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
    Region:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
      - id
      - name
      additionalProperties: false
  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
  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.