cruise-itinerary-com Price index API

openapi: 3.2.0
info:
  title: Cruise Itinerary Data Price index 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: Price index
paths:
  /v1/price-index/latest:
    get:
      tags:
      - Price index
      summary: Latest price index
      description: The all-lines Cruise Price Index plus the eight largest lines, for cabin `any` and segment `all`, over the last 12 loads. Ordered all lines first, then by line name, oldest load first. The series starts on 2026-09-06 at 100.
      operationId: getPriceIndexLatest
      x-required-plan: free
      parameters: []
      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/PriceIndexPoint'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - observed_on: '2026-09-06'
                  previous_on: null
                  line: null
                  cabin: any
                  segment: all
                  weighting: sailing
                  matched: 54299
                  index_value: 100
                  mean_log_change: null
                  pct_cut: null
                  pct_raised: null
                  pct_unavailable: null
                  avg_per_diem: null
                  berth_coverage_pct: null
                - observed_on: '2026-09-07'
                  previous_on: '2026-09-06'
                  line: null
                  cabin: any
                  segment: all
                  weighting: sailing
                  matched: 54299
                  index_value: 99.9036
                  mean_log_change: -0.000964
                  pct_cut: 0.62
                  pct_raised: 0.52
                  pct_unavailable: 0.18
                  avg_per_diem: 464.59
                  berth_coverage_pct: null
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 71
                  total: 71
                  has_more: false
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
  /v1/price-index:
    get:
      tags:
      - Price index
      summary: Price index series
      description: The full series for one line, cabin, segment and weighting, oldest first. `line` is a slug, or omitted (or `all`) for all lines. `weighting=berth` weights each sailing by its ship's lower berths (passengers per sailing) instead of counting each sailing once. Rows exist only where at least 30 sailings matched.
      operationId: getPriceIndex
      x-required-plan: business
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      - name: line
        in: query
        required: false
        description: Line slug or all.
        schema:
          type: string
        example: carnival-cruise-line
      - name: cabin
        in: query
        required: false
        description: Cabin class (default any).
        schema:
          type: string
          enum:
          - inside
          - outside
          - balcony
          - suite
          - any
      - name: segment
        in: query
        required: false
        description: all (default), w000_090, w091_180, w181_365, w366_plus, a sail quarter like q2027_1, or size_intimate, size_small, size_medium, size_large, size_mega.
        schema:
          type: string
        example: w000_090
      - name: weighting
        in: query
        required: false
        description: sailing (default) or berth.
        schema:
          type: string
          enum:
          - sailing
          - berth
      - name: from
        in: query
        required: false
        description: Earliest observed_on.
        schema:
          type: string
          format: date
        example: '2026-09-06'
      - name: to
        in: query
        required: false
        description: Latest observed_on.
        schema:
          type: string
          format: date
        example: '2026-09-28'
      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/PriceIndexPoint'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
              example:
                data:
                - observed_on: '2026-09-06'
                  previous_on: null
                  line:
                    id: carnival-cruise-line
                    name: Carnival Cruise Line
                  cabin: balcony
                  segment: w000_090
                  weighting: sailing
                  matched: 300
                  index_value: 100
                  mean_log_change: null
                  pct_cut: null
                  pct_raised: null
                  pct_unavailable: null
                  avg_per_diem: null
                  berth_coverage_pct: null
                - observed_on: '2026-09-07'
                  previous_on: '2026-09-06'
                  line:
                    id: carnival-cruise-line
                    name: Carnival Cruise Line
                  cabin: balcony
                  segment: w000_090
                  weighting: sailing
                  matched: 300
                  index_value: 100.3153
                  mean_log_change: 0.003148
                  pct_cut: 3
                  pct_raised: 7
                  pct_unavailable: 2.28
                  avg_per_diem: 150.02
                  berth_coverage_pct: null
                - observed_on: '2026-09-14'
                  previous_on: '2026-09-07'
                  line:
                    id: carnival-cruise-line
                    name: Carnival Cruise Line
                  cabin: balcony
                  segment: w000_090
                  weighting: sailing
                  matched: 255
                  index_value: 100.3892
                  mean_log_change: 0.000737
                  pct_cut: 51.76
                  pct_raised: 42.35
                  pct_unavailable: 13.56
                  avg_per_diem: 148.1
                  berth_coverage_pct: null
                meta:
                  as_of: '2026-10-19'
                  page: 1
                  per_page: 50
                  total: 8
                  has_more: false
        '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
    Ref:
      type: object
      properties:
        id:
          type: string
          description: Slug.
        name:
          type: string
      required:
      - id
      - name
      additionalProperties: false
    PriceIndexPoint:
      type: object
      properties:
        observed_on:
          type: string
          format: date
        previous_on:
          oneOf:
          - type: string
            format: date
          - type: 'null'
        line:
          oneOf:
          - $ref: '#/components/schemas/Ref'
          - type: 'null'
        cabin:
          type: string
          enum:
          - inside
          - outside
          - balcony
          - suite
          - any
        segment:
          type: string
          description: all, a booking window (w000_090, w091_180, w181_365, w366_plus), a sail quarter such as q2027_1, or a ship size class (size_intimate, size_small, size_medium, size_large, size_mega).
        weighting:
          type: string
          description: 'sailing: each matched sailing counts once (the published index). berth: each sailing weighted by its ship''s lower berths; sailings with no berth count are left out.'
          enum:
          - sailing
          - berth
        matched:
          type: integer
          description: Sailings priced in both loads.
        index_value:
          type: number
          description: Chained index, 100 on 2026-09-06.
        mean_log_change:
          oneOf:
          - type: number
            description: Mean of ln(new/old) over matched sailings, each winsorized to -0.5..0.5.
          - type: 'null'
        pct_cut:
          oneOf:
          - type: number
            description: Percent of matched sailings whose fare fell.
          - type: 'null'
        pct_raised:
          oneOf:
          - type: number
          - type: 'null'
        pct_unavailable:
          oneOf:
          - type: number
            description: Percent priced before and unpriced now, still listed.
          - type: 'null'
        avg_per_diem:
          oneOf:
          - type: number
            description: Mean fare per night, USD, over the matched set.
          - type: 'null'
        berth_coverage_pct:
          oneOf:
          - type: number
            description: 'berth rows only: percent of the matched sailings whose ship has a berth count. Null for sailing rows.'
          - type: 'null'
      required:
      - observed_on
      - previous_on
      - line
      - cabin
      - segment
      - weighting
      - matched
      - index_value
      - mean_log_change
      - pct_cut
      - pct_raised
      - pct_unavailable
      - avg_per_diem
      - berth_coverage_pct
      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.